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 for details.

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.

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.

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 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 unused 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.

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.

plugins:
        - hyde.ext.plugins.meta.MetaPlugin
        - hyde.ext.plugins.blockdown.BlockdownPlugin

Context Data

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 {{app.current_version}} in any template will output 0.6.

context:
    data:
        app:
            current_version: 0.6

Context Data 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 a provider.

For example, consider the following snippets:

context:
    providers:
        versions: app-versions.yaml

latest: 0.6

This would import the data in app-versions.yaml into context[versions]. This data can be used directly in templates in this manner: {{ versions.latest }}.

Markdown

Extensions and extension configuration for markdown can be configured in the markdown property. You can read about markdown extensions in python markdown documentation.

The following configuration:

markdown:
    extensions:
        - def_list
        - tables
        - headerid

will use the def_list, tables and headerid extensions in python markdown.