diff --git a/hyde/layouts/doc/content/configuration.html b/hyde/layouts/doc/content/configuration.html new file mode 100644 index 0000000..0ba67d8 --- /dev/null +++ b/hyde/layouts/doc/content/configuration.html @@ -0,0 +1,164 @@ +=== +title: Configuration +subtitle: change hyde to match your style +created: 2011-01-28 01:30:05 +=== + +§§ blurb + +Hyde is configured using one or more `yaml` files. On top of all +the niceties `yaml` provides out of the box, hyde also adds a few +power features to manage complex websites. + +If a site has a `site.yaml` 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 +[command line reference][commandline] for details. + +§§ /blurb + +## Inheritance + +Configuration files can inherit from another file using the +`extends` option. + +For example, the following configuration will inherit all properties +from `site.yaml` and override the `mode` property. + +~~~yaml~~~ +extends: site.yaml +mode: production +~~~~~~~~~~ + +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 `/media` but on production you may have a subdomain and want +the media to come from `http://abc.example.com/media`. + +This can be accomplished by creating an _extended_ configuration file and +overriding the media_url property. For a real world example, you can take +a look at the [source of this documentation][hydedocpages]. + +## Paths & Urls + +The following path & url properties can be defined for use in templates: + +`media_root` +: 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. + + _Optional_. Default: `media` + +`media_url` +: The url prefix for serving media files. If you are using a CDN 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. + + _Optional_. Default: `/media` + +`base_url` +: 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. + + _Optional_. Default: `/` + +`deploy_root` +: 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 [command line][commandline] using + the `-d` option. + +## Plugins & templates + +`template` +: 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 `Jinja2` are supported, so the `template` setting + is a NOOP at the moment. + + _Optional_. Default: `hyde.ext.templates.jinja.Jinja2Template` + +`plugins` +: 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 + [plugin documentation][plugins]. + + _Optional_. Default: No plugins are loaded. + + The following configuration option would load the metadata plugin + and the blockdown plugin and execute events in the same order. + + ~~~yaml~~~ + plugins: + - hyde.ext.plugins.meta.MetaPlugin + - hyde.ext.plugins.blockdown.BlockdownPlugin + ~~~~~~~~~~~ + +## Context + +The context section contains key / value pairs that are simply passed +on to the templates + +_Optional_. Default: No context variables are defined. + +For example, given the following configuration, the statement +`{%raw%}{{hyde.current_version}}{%endraw%}` in any template +will output `0.6`. + +~~~yaml~~~ +context: + hyde: + current_version: 0.6 +~~~~~~~~~~~ + +## Providers + +Providers are special constructs used to import data into the context. +For example, data from a database can be exported as `yaml` and imported +as providers. + +For example, consider the following snippet: + +~~~yaml~~~ +context: + providers: + versions: hyde-versions.yaml +~~~~~~~~~~~ + +This would import the data in `hyde-versions.yaml` into `context[versions]`. +This data can be used directly in templates in this manner: +`{%raw%}{{ versions.latest }}{%endraw%}`. + + +## Markdown + +Extensions and extension configuration for markdown can be configured in the +`markdown` property. You can read about markdown extensions in +[python markdown documentation][pymarkdown]. + +The following configuration: + +~~~yaml~~~ +markdown: + extensions: + - def_list + - tables + - headerid +~~~~~~~~~~ + +will use the [def_list][], [tables][] and [headerid][] extensions in python markdown. + + +[commandline]: [[commandline.html]] +[plugins]: [[plugins.html]] +[pymarkdown]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions +[hydedocpages]: https://github.com/hydepy/hyde/blob/master/hyde/layouts/doc/pages.yaml +[def_list]: http://www.freewisdom.org/projects/python-markdown/Definition_Lists +[headerid]: http://www.freewisdom.org/projects/python-markdown/HeaderId +[tables]: http://www.freewisdom.org/projects/python-markdown/Tables diff --git a/hyde/layouts/doc/content/media/css/inc/text.less b/hyde/layouts/doc/content/media/css/inc/text.less index 8207538..b97e6da 100644 --- a/hyde/layouts/doc/content/media/css/inc/text.less +++ b/hyde/layouts/doc/content/media/css/inc/text.less @@ -26,8 +26,8 @@ h1, h2, h3, h4, h5, h6{ code, .highlight pre{ font-family: "Courier New", courier, monospace; - font-size: 80%; - line-height: 110%; + font-size: 90%; + line-height: 100%; } code{