Metadata and template bindings¶

(This is a continuation of the second section of the tutorial entitled Adding assets.)

You may have seen that since the last iteration of the template, we now have a <title> tag. It would be a good thing to have it filled with the title of each document. For this, additional bindings should be passed to the template. This can be done by providing metadata about each file (and even directories).

We will start by setting metadata on second.html. Metadata are looked up in *.meta.py files. Hence, we are going to create a second.html.meta.py file next to second.html, with the following content:

title = 'The second page'

Metadata files are Python files so you may import modules, compute things, etc. All symbols that are local to the file will be available in a binding called md in the template.

We could hence change the template like this (changes appear on the highlighted line):

<!DOCTYPE html>
<html>
<head>
  <title tal:content="md['title']"/>
  <link rel="stylesheet" type="text/css" href="css/style.css"/>
</head>
<body>
<div class="content" tal:content="structure body"/>
<div class="footer">Generated by Soho.</div>
</body>
</html>

We did set metadata for the second.html file but not for index.rst. We could create an index.rst.meta.py like we did above, but reStructuredText files can embed metadata. We will indicate the title in the file itself, like this (see highlighted lines):

.. meta::
   :title: The home page

This is the **home** page. Look, here is a `link`_ to the second page.

.. _link: second.html

We are ready to run Soho again:

$ cd $SITE_ROOT
$ ls src
index.rst    second.html    second.html.meta.py
$ soho-build -f
[...]

You should now see the title of each page in your web browser.

In fact, metadata can be set on directories in files named .meta.py. The metadata of each file automatically inherits from the metadata of the directory it lives in, as well as the directory above (if any), and so on and so forth. We will see a use-case for this in the next section entitled Internationalization and metadata on directory.