Getting started =============== Exhibition is fairly quick to configure. Minimum setup ------------- At minimum, Exhibition expects to find a YAML file, ``site.yaml``, with at least ``deploy_path`` and ``content_path`` defined. The path specified in ``content_path`` needs to exist. For example: .. code-block:: shell $ mkdir content $ cat << EOF > site.yaml > deploy_path: deploy > content_path: content > EOF .. note:: Exhibition comes with a starter template for new sites. See ``exhibit create --help`` for more information. You can now generate your first Exhibition website!: .. code-block:: shell $ exhibit gen $ ls deploy Of course, you've got no content so the directory will be empty. Any file or directory you put in ``content`` will appear in ``deploy`` when you run ``exhibit gen``. Templates --------- Exhibition supports `Jinja2 `_ out of the box, but it needs to be enabled: .. code-block:: yaml :caption: site.yaml deploy_path: deploy content_path: content filter: exhibition.filters.jinja2 templates: templates Now we can create HTML files that use Jinja2 template syntax: .. code-block:: html+jinja :caption: content/index.html

This page has {{ node.siblings|length }} siblings

.. note:: ``node`` is the current page being rendered and is passed to Jinja2 as a context variable. Run ``exhibit gen`` and then ``exhibit serve``. If you connect to ``http://localhost:8000`` you'll see the following text:: This page has 0 siblings If you add another page, this number will increase when run ``exhibit gen`` again. If you wish to use template inheritance, create a directory named "templates" and add your templates to it. You can either use the extends tag directly or you can specify ``extends`` in ``site.yaml``. You can also specify ``default_block`` to save you from wrapping every page in ``{% block content %}``: .. code-block:: yaml extends: page.j2 default_block: content And then our template: .. code-block:: html+jinja :caption: templates/page.j2 {% block content %}{% endblock %} Our index page would be this: .. code-block:: html+jinja :caption: content/index.html

This page has {{ node.siblings|length }} siblings

The generated HTML will be exactly the same, except now files in ``content/`` will not have to each have their own copy of any headings, page title, links to CSS or whatever. Meta ---- Site settings are available in templates as ``node.meta``. For example: .. code-block:: html+jinja :caption: content/otherpage.html

Current filter is "{{ node.meta.filter }}"

Which will generate the following:: Current filter is "exhibition.filters.jinja2" You can reference any data that you put in ``site.yaml`` like this - and there's no limit on what you can put in there. As well as ``site.yaml`` there are two additional places that settings can be controlled: ``meta.yaml`` and frontmatter. Meta files ^^^^^^^^^^ A ``meta.yaml`` can be used to define or override settings for a particular directory and any files or subdirectories it contains. Let's add a blog to our website: .. code-block:: shell $ mkdir content/blog $ cat << EOF > content/blog/meta.yaml > extends: blog_post.j2 Now all HTML files in ``content/blog/`` will use the ``blog_post.j2`` as their base template rather than ``page.j2``, but files such as ``content/index.html`` will still use ``page.j2`` as their base template. .. note:: ``meta.yaml`` files do not appear as nodes and won't appear in ``deploy_path`` Frontmatter ^^^^^^^^^^^ Frontmatter is the term used to describe YAML metadata put at the beginning of a file. Unlike ``meta.yaml``, any settings defined (or overridden) here will only affect this one file. For example, we won't want the index page of our blog to use ``blog_post.j2`` as its base template: .. code-block:: html+jinja :caption: content/blog/index.html --- extends: blog_index.j2 --- {% for post in node.sibling %}

{{ post.meta.title }}

.. code-block:: html+jinja :caption: content/blog/first-post.html --- title: My First Post ---

{{ node.meta.title }}

Hey! This is my first blog post!

What next? ---------- Checkout the :doc:`API `. File bugs. Submit patches. Exhibition is still in the early stages of development, so please contribute!