Adding paths to your Flourish site
Once you have added some sources and created the generate.py script, you need to add paths in order to create any HTML.
In your generate.py
, you will need a list of generators:
PATHS = (
SourceGenerator(
name = 'source',
path = '/#slug',
),
...
)
Each generator has two mandatory arguments, name
and path
, and will
produce all possible variations of a given path.
name
The name
argument to a generator is a unique symbolic representation of
what this generator produces. For example, homepage
or year-index
.
The name is most commonly used in the
path()
template function
for producing paths without hard-coding them. With the exception of the
special case name source
, they have no other meaning.
The special name source
One name is treated slightly differently. If you declare a name of source
on a generator, it is treated by Flourish to represent the canonical path
of every source. When you get the link to a source using the source.url
method, it will use this path, even if other generators will also create
pages from that source.
path
The path is where in the site the page(s) are generated.
A hash (#
) in the path represents a replaceable token that will be
substituted as the output is generated. The alphanumerics that follow the hash
represent the key to use (as found in source TOML).
Automatic tokens
The following tokens are automatically available without you having to add them explicitly to your sources:
slug
— always comes from the filename of the source TOML, JSON, or Markdown file (explained further in Adding Sources)year
,month
,day
— are created from thepublished
key, if it is a timestamp (explained further in Adding sources)
In the example above, the path was /#slug
. This means each source will be
generated at a path that matches the slug of the source. For example, a source
file photos/grand-canyon.toml
has the slug photos/grand-canyon
, so the
path would be /photos/grand-canyon
. Note the absence of /
at the start of
the slug, which is why the path adds it explicitly.
Multiple tokens in a path
Using the slug is the most common pattern for creating output from sources,
but you are not restricted to only this. Some blogs commonly have posts that
indicate the date of publication, this can be done by using a path such as
/#year/#month/#slug
. Your source doesn't have to be located within a
year/month directory structure, instead that comes from the published
timestamp.
For example, if the photos/grand-canyon.toml
contained this published
timestamp:
published = 2016-02-14T13:56:22Z
then the generated path would be /2016/02/photos/grand-canyon
.
Multiple pages from single tokens
If a path has a token with more than one possible subtitution, then multiple
pages are generated. For example, for a source URL path of
/#year/#month/#slug
all three tokens only have one value, so only one page
would be generated. However, if you had a source file example-page.toml
,
containing these keys:
title = 'Example page'
tag = ['sample', 'introduction']
then the source URL path /#tag/#slug
would generate two pages:
/sample/example-page
/introduction/example-page
This is more commonly used for index pages (eg /archives/#year
,
/tags/#tag
) than it is for sources, which usually only have the one,
canonical, path.
context
Extra values to be passed to the template's context.