Adding sources to Flourish

Flourish uses source files to contain the content of site to be generated.

Four types of source file are supported, and they can be mixed and matched at will:

All sources are treated as though they contain UTF-8 content. If they contain characters of a different character set, you will have problems. Modern text editors save files in UTF-8 by default.

The slug

The filename and subdirectory/-ies of the source file determines the default URL that piece of content will have in the site, also known as the "slug". The filename (slug) can only contain letters, numbers, hyphens (-) and underscores (_). It cannot contain other punctuation characters, such as periods (.) or quotation marks ('").

  • Correct filenames:
    • about-me.toml
    • 2016/06/02/valentines-day.markdown
  • Incorrect filenames:
    • about.me.toml
    • 2016/06/02/valentine's-day.markdown

Note: a slug that ends /index will be trimmed to ending / when treated as a URL. For example, a source file more/about/index.toml will have the slug more/about/index and the URL more/about/ when rendered.

Slugs in CSV sources

When using CSV files to add multiple sources, the slug cannot come from the filename of the CSV or each row would have the same slug. Instead there should be a slug column in the CSV. The same rules on valid slugs apply to this column.

Source data

A source is a set of keys and values. These specify aspects of a web page, such as the title, content, when it was created, and anything else you might need.

Example TOML source

# example TOML file

body_markdown = """
# Example blog post

I am a blog post, written in Markdown.
"""

published = 2016-07-01T12:00:00Z
tag = ['example', 'toml']
title = 'A TOML example'
page_type = 'post'

For more information on the rules of correctly formatting TOML sources, see the TOML specification.

The first thing to note from this example is the key body_markdown. Flourish will automatically process Markdown content in any key that ends _markdown and make the resulting HTML available as that key minus the _markdown. So in this example body would contain HTML (also see "Adding Markdown to sources" below).

Second, the key published contains a timestamp. This is in a specific format, called ISO 8601. Although this format supports more variation, Flourish currently only understands timestamps in the format YYYY-MM-DDTHH:MM:SSZ (the year, a hyphen, the month as two digits, a hyphen, the day of the month as two digits, the letter T, the hours of the day expressed as a 24-hour clock, a colon, the minutes, a colon, the seconds, and lastly the letter Z). This expresses the time as being in UTC (or Greenwich Mean Time). Better support for dates and times outside of UTC will come in a later version.

Example Markdown source

---
published = 2016-07-01T12:00:00Z
tag = ['example', 'markdown']
title = 'A Markdown example'
---

# Another example blog post

I am a blog post, also written in Markdown.

Note that this example demonstrates that you can embed TOML in the Markdown file by putting it at the very top of the file and surrounding it with triple hyphens on a line by themselves. The TOML can also be surrounded by triple backticks (```).

The content of the file (without the embedded TOML) is put into the key body_markdown (identical to the Markdown in the TOML in the first example).

This technique of including metadata in a Markdown file is called "front matter". Note that it is entirely optional, and a source can contain just Markdown without any front matter.

Adding Markdown to sources

In addition to putting the Markdown in the source as shown in the examples above, there is a second way to add Markdown content — by using associated filenames.

Any source can have other Markdown content added from separate files, providing that they share the slug part of the filename. For example, a source with the filename blog-post.toml, will automatically contain the content of the file blog-post.body.markdown as though it had been in the key body_markdown in the TOML.

The advantage of having separate files for the Markdown is readability — both the original source file and the Markdown are more easily understood when looking at them as separate entities.

The disadvantage is having to deal with more files, and it not being immediately obvious when looking at a source file that it may have more keys that are currently shown.

Example sources from a CSV file

slug,title,published,body_markdown
hello-world,"Hello world",2021-04-06T17:00:00Z,"# Hello world!"
goodbye-world,"Goodbye world",2021-04-06T17:30:00Z,"# Goodbye world."

Adding HTML to sources

In the same manner as adding Markdown shown above, raw HTML can be added. For example, a source with the filename blog-post.toml will automatically contain the content of the file blog-post.body.html as though it had been in the key body in the TOML.

Special keys in sources

You are free to use any keys for any purpose in your Flourish source documents, but the following keys have special treatment you should be aware of:

  • author — is used to mark the author of a source when generating Atom feeds (this overrides the author set in the site configuration for that source only).
  • body — is used as the content of an individual source when generating Atom feeds.
  • published — is used as the publication timestamp of a source when generating Atom feeds, and is used as the basis of the #year, #month and #day special tokens in paths. It is expected to be a timestamp (explained in Adding sources).
  • title — is used as the title of an individual source when generating Atom feeds.
  • updated — is used as the "last updated" timestamp of a source when generating Atom feeds. It is expected to be a timestamp (explained in Adding sources).
  • ..._fkey — anything ending _fkey is assumed to be part of a foreign key lookup. See the advanced topic Linking sources together.
  • ..._set — anything ending _set is assumed to be part of a reverse foreign key lookup. See the advanced topic Linking sources together.
  • previous_slug — is an array of strings that represent the previous location that source would have been found on the site, in the event that you wish to change the path. The Flourish preview server and S3/CloudFront will serve them as 301 Moved Permanently responses.