Generating the HTML

Once you have added some sources, created the generate.py script, and added some paths, you need to know how the HTML is generated.

Source pages

The default declaration for generating each source to an individual output page in a Flourish site is:

SOURCE_URL = (
    '/#slug',
    PageGenerator.as_generator(),
)

In between the brackets are two arguments. The first is the path, explained in Adding paths; the second is what code should be run to create each page.

The code PageGenerator.as_generator() will pass all of the key/value pairs defined in the source to a template, render the template, and use the result to write to the output HTML page.

Default source page template

By default, this code will expect to use a template called page.html. A short example of this template looks like:

<!DOCTYPE html>
<html>
<head>
  <title>{{title}}</title>
</head>
<body>
  {{body}}
</body>
</html>

The parts surrounded by double curly brackets (eg {{title}}) are substitutions that use the value from the source. For example, this template used against this source:

title = "Example page"
body = "<p>Hello world.</p>"

would create the following HTML:

<!DOCTYPE html>
<html>
<head>
  <title>Example page</title>
</head>
<body>
  <p>Hello world.</p>
</body>
</html>

Overriding the default template

If you need to use a different template from page.html to render a given source, you can set one of two keys:

  • page_type — the template becomes the value of this key with .html added; for example a source with page_type = 'photo' in its configuration will try to use the template photo.html.
  • template — the template becomes the value of this key with no modification; for example template = 'pages/awesome-page.html'

If both keys are set, the value of template is used.

Index pages

To create the pages that link to your sources, you would use a URL declaration like:

URLS = (
    (
        '/',
        'homepage',
        IndexGenerator.as_generator()
    ),
)

In between the brackets are three arguments. The first is the URL path, explained in Adding URLs; the second is a symbolic name to represent this page; the third is what code should be run to create it.

The code IndexGenerator.as_generator() will pass a list of all matching sources to a template, render the template, and use the result to write to the output HTML page.

Default index page template

By default, this code will expect to use a template called index.html. A short example of this template looks like:

<!DOCTYPE html>
<html>
<head>
  <title>Index of pages</title>
</head>
<body>
  <ul>
    {% for page in pages %}
      <li>
        <a href='{{page.url}}'>{{page.title}}</a>
      </li>
    {% endfor %}
  </ul>
</body>
</html>

In the template pages is the list of all matching sources. This template loops over each source within that (each being set to the variable page), and uses keys from the source to link to the source page.

More about the template language

Flourish uses Jinja2 to render templates. You can learn a lot more about the things you can do in your templates by reading the Jinja2 documentation.