-
Notifications
You must be signed in to change notification settings - Fork 1
/
config.html
250 lines (237 loc) · 14.2 KB
/
config.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<!doctype html>
<!-- https://github.com/paulirish/html5-boilerplate/blob/master/index.html -->
<!-- paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/ -->
<!--[if lt IE 7 ]> <html lang="en" class="no-js ie6"> <![endif]-->
<!--[if IE 7 ]> <html lang="en" class="no-js ie7"> <![endif]-->
<!--[if IE 8 ]> <html lang="en" class="no-js ie8"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!--> <html lang="en" class="no-js"> <!--<![endif]-->
<head>
<meta charset="utf-8">
<!-- Always force latest IE rendering engine (even in intranet) & Chrome Frame
Remove this if you use the .htaccess -->
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<!-- encoding must be specified within the first 512 bytes
www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset -->
<!-- meta element for compatibility mode needs to be before
all elements except title & meta
msdn.microsoft.com/en-us/library/cc288325(VS.85).aspx -->
<!-- Chrome Frame is only invoked if meta element for
compatibility mode is within the first 1K bytes
code.google.com/p/chromium/issues/detail?id=23003 -->
<title>Configuration</title>
<meta name="description" content="Awesome documentation for hyde - a python static website generator
">
<meta name="author" content="Lakshmi Vyasarajan">
<!-- Mobile viewport optimized: j.mp/bplateviewport -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Place favicon.ico & apple-touch-icon.png
in the root of your domain and delete these references -->
<link rel="shortcut icon" href="/favicon.ico">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<script type="text/javascript" src="http://use.typekit.com/hyw1bsz.js"></script>
<script type="text/javascript">try{Typekit.load();}catch(e){}</script>
<link rel="stylesheet" href="/media/css/site.css">
<link rel="stylesheet" href="/media/css/syntax.css">
<!-- All JavaScript at the bottom, except for Modernizr which
enables HTML5 elements & feature detects -->
<script src="/media/js/libs/modernizr-1.6.min.js"></script>
</head>
<body id="config">
<div id="container">
<div id="main" role="main">
<header class="banner clearfix">
<img src="/media/img/hyde-logo-128.png">
<h1>hyde</h1>
<h3>A static website generator</h3> </header>
<div class="doc">
<article>
<hgroup>
<h1 class="title">Configuration</h1>
<h3 class="subtitle">change hyde to match your style</h3>
</hgroup>
<p>Hyde is configured using one or more <code>yaml</code> files. On top of all
the niceties <code>yaml</code> provides out of the box, hyde also adds a few
power features to manage complex websites.</p>
<p>If a site has a <code>site.yaml</code> file in the root directory it is used
as the configuration for generating the website. This can be
overridden by providing a command line option. See the
<a href="/commands">command line reference</a> for details.</p>
<h2 id="inheritance">Inheritance</h2>
<p>Configuration files can inherit from another file using the
<code>extends</code> option.</p>
<p>For example, the following configuration will inherit all properties
from <code>site.yaml</code> and override the <code>mode</code> property.
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">extends</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">site.yaml</span><br /><span class="l-Scalar-Plain">mode</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">production</span><br /></pre></div><br /><figcaption><span class="caps">YAML</span></figcaption></figure></div></p>
<p>This is useful for customizing the site to operate in different modes.
For example, when running locally you may want your media files to
come from <code>/media</code> but on production you may have a subdomain and want
the media to come from <code>http://abc.example.com/media</code>.</p>
<p>This can be accomplished by creating an <em>extended</em> configuration file and
overriding the <code>media_url</code> property. For a real world example, you can take
a look at the <a href="https://github.com/hyde/hyde/blob/master/hyde/layouts/doc/pages.yaml">source of this documentation</a>.</p>
<h2 id="paths__urls">Paths <span class="amp">&</span> Urls</h2>
<p>The following path <span class="amp">&</span> url properties can be defined for use in templates:</p>
<dl>
<dt><code>media_root</code></dt>
<dd>
<p>The root path where media files(images, css, javascript etc.,)
can be found. This may be used by plugins for special processing.
If your website does not have a folder that contains all media,
you can safely omit this property.</p>
<p><em>Optional</em>. Default: <code>media</code></p>
</dd>
<dt><code>media_url</code></dt>
<dd>
<p>The url prefix for serving media files. If you are using a <span class="caps">CDN</span> like
Amazon S3 or the Rackspace cloud and host all your media files from
there, you can make use of this property to specify the prefix for
all media files.</p>
<p><em>Optional</em>. Default: <code>/media</code></p>
</dd>
<dt><code>base_url</code></dt>
<dd>
<p>The base url from which the site is served. If you are hosting the
website in a subdomain or as part of a larger website, you can specify
this property to indicate the path of this project in your website.</p>
<p><em>Optional</em>. Default: <code>/</code></p>
</dd>
<dt><code>deploy_root</code></dt>
<dd>
<p>Where the generated files should go. This can either be a relative
path from the root of the site source or an absolute path. Note that
this can also be overridden in the <a href="/commands">command line</a> using
the <code>-d</code> option.</p>
</dd>
</dl>
<h2 id="plugins__templates">Plugins <span class="amp">&</span> templates</h2>
<dl>
<dt><code>template</code></dt>
<dd>
<p>The template engine to use for processing the website can be specified
in the configuration file as a python class path. Currently no other
templates apart from <code>Jinja2</code> are supported, so the <code>template</code> setting
is a unused at the moment.</p>
<p><em>Optional</em>. Default: <code>hyde.ext.templates.jinja.Jinja2Template</code></p>
</dd>
<dt><code>plugins</code></dt>
<dd>
<p>Plugins are specified as list of python class paths. Events that are
raised during the generation of the website are issued to the plugins
in the same order as they are listed here. You can learn more about
how the individual plugins themselves are configured in the
<a href="/plugins">plugin documentation</a>.</p>
<p><em>Optional</em>. Default: No plugins are loaded.</p>
<p>The following configuration option would load the metadata plugin
and the blockdown plugin and execute events in the same order.
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">plugins</span><span class="p-Indicator">:</span><br /> <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">hyde.ext.plugins.meta.MetaPlugin</span><br /> <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">hyde.ext.plugins.blockdown.BlockdownPlugin</span><br /></pre></div><br /><figcaption><span class="caps">YAML</span></figcaption></figure></div></p>
</dd>
</dl>
<h2 id="context_data">Context Data</h2>
<p>The context section contains key / value pairs that are simply passed
on to the templates</p>
<p><em>Optional</em>. Default: No context variables are defined.</p>
<p>For example, given the following configuration, the statement
<code>{{app.current_version}}</code> in any template
will output <code>0.6</code>.
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">context</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">data</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">app</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">current_version</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0.6</span><br /></pre></div><br /><figcaption><span class="caps">YAML</span></figcaption></figure></div></p>
<h2 id="context_data_providers">Context Data Providers</h2>
<p>Providers are special constructs used to import data into the context.
For example, data from a database can be exported as <code>yaml</code> and imported
as a provider.</p>
<p>For example, consider the following snippets:
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">context</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">providers</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">versions</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">app-versions.yaml</span><br /></pre></div><br /><figcaption><span class="caps">YAML</span></figcaption></figure></div></p>
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">latest</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0.6</span><br /></pre></div><br /><figcaption>app-versions.yaml</figcaption></figure></div>
<p>This would import the data in <code>app-versions.yaml</code> into <code>context[versions]</code>.
This data can be used directly in templates in this manner:
<code>{{ versions.latest }}</code>.</p>
<h2 id="markdown">Markdown</h2>
<p>Extensions and extension configuration for markdown can be configured in the
<code>markdown</code> property. You can read about markdown extensions in
<a href="http://www.freewisdom.org/projects/python-markdown/Available_Extensions">python markdown documentation</a>.</p>
<p>The following configuration:
<div class="codebox"><figure class="code"><div class="highlight"><pre><span class="l-Scalar-Plain">markdown</span><span class="p-Indicator">:</span><br /> <span class="l-Scalar-Plain">extensions</span><span class="p-Indicator">:</span><br /> <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">def_list</span><br /> <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">tables</span><br /> <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">headerid</span><br /></pre></div><br /><figcaption><span class="caps">YAML</span></figcaption></figure></div></p>
<p>will use the def_list, tables and headerid extensions in python markdown.</p> </article>
<aside>
<ul class="toc">
<li><mark class="version">Version: 0.8</mark></li>
<li class="topic" id="topic1">
<ul class="links">
<li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/index.html">
Overview</a> </li>
</ul>
</li><li class="topic" id="topic2">
<h2 class=" active">Getting Started</h2> <ul class="links">
<li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/install.html">
Installation</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/commands.html">
Command Line</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/server.html">
Hyde web server</a><li>
<a class="active" title="Awesome documentation for hyde - a python static website generator
"
href="/config.html">
Configuration</a> </li>
</ul>
</li><li class="topic" id="topic3">
<h2 class="">Templating Guide</h2> <ul class="links">
<li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/templates/index.html">
Creating layouts</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/templates/context.html">
Context Variables</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/templates/markrefer.html">
References</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/templates/text.html">
Text</a><li>
<a title="Awesome documentation for hyde - a python static website generator
"
href="/templates/traversing.html">
Traversing</a> </li>
</ul>
</li> </ul>
<nav class="prevnext">
<a
class="prev"
title="Hyde web server"
href="/server.html">
←Previous
</a> <a
class="next"
title="Creating layouts"
href="/templates/index.html">
Next→
</a> <br class="clear">
</nav>
</aside>
</div>
<footer>
<p><a href="https://github.com/hyde/hyde">smelted with hyde</a> —
<a href="https://github.com/hyde/hyde.github.com/issues">spot <span class="amp">&</span> complain</a> —
<a href="https://github.com/hyde/docs">fork <span class="amp">&</span> fix</a></p></footer> </div>
<footer>
</footer>
</div> <!--! end of #container -->
<!-- Javascript at the bottom for fast page loading -->
<!-- Grab Google CDN's jQuery. fall back to local if necessary -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.js"></script>
<script>!window.jQuery && document.write(unescape('%3Cscript src="/media/js/libs/jquery-1.4.4.min.js"%3E%3C/script%3E'))</script>
</body>
</html>