Home > Content

This page details the content/ directory of a Basildon site. All pages of a site live in the content directory: each is a separate text file, and the file names and directory hierarchy are not prescribed. Content files have two parts: one, a Yaml-formatted frontmatter, delimited by three hyphens; and two, a main body that can be in any format. The file extension should match the format of the body; often this is Markdown (.md), but it doesn't have to be — you could easily have all your content files be HTML if that suits your site better.

An example of a page file at content/topics/

title: Goats
description: Goats are good example animals.

This is the part where we explain more about the 'goat' topic.

Because content is usually in Markdown format, there are some useful Markdown additions that can be used in content pages. The rest of this page explains these.

All the metadata from content files is read into an SQLite database when a site is built, which can be queried in templates (see that page for more information about how). The database can also be modified and the changes written back to the content files.


Local images should be stored in the content/ directory, and included with the normal Markdown syntax. Their file paths should be relative to their own location and not start with a slash.

For example, an image file stored at content/images/file.png should be referenced like this:

For information about other assets such as stylesheets and scripts, see the Assets section of the documentation overview.


This section documents 'shortcodes', which are what we call specific replacable parts in a Markdown document. They are inline phrases or blocks of text such as {foo} or {{{bar id=123}}} which get replaced by the contents of templates such as templates/shortcodes/foo.html.twig or templates/shortcodes/bar.tex.twig.

Shortcodes replace an earlier feature in Basildon called 'embeds'. The functionality of embeds can be achieved with shortcodes, along with a lot more.

The term 'shortcode' (as well as the older 'embed') comes from WordPress, which has a similar function.

Shortcodes are a simple way to include images, videos, and summaries of other web pages. For example, this is a photo from Wikimedia Commons:

The Co-op, Post Office, and Courthouse on Stirling Terrace in York, Western Australia.
The Co-op, Post Office, and Courthouse on Stirling Terrace in York, Western Australia.

It is added to the source Markdown with this:

{{{commons file=Co-Op,_Post_Office,_Courthouse.jpg }}}

All of the other information (image URL, caption, etc.) is retrieved from the Commons API when the Markdown is rendered.

Shortcodes can be rendered to any output format; they're not limited to HTML.


To configure a new shortcode, add a file to the templates' directory, with a name matching what you want to use in the Markdown.

The file templates/shortcodes/<shortcode-name>.<format>.twig to contain the HTML or other output that should be output for the shortcode.

The following variables are available in shortcode templates:

Example: Wikimedia Commons

In any Markdown file:

{{{commons file=Example.jpg}}}

In templates/shortcodes/commons.html.twig:

{% set commons = commons(shortcode.attr('file')) %}
    <a href="{{ commons.imageinfo.0.descriptionurl }}">
        <img src="{{ image_url( commons.imageinfo.0.thumburl ) }}"
             width="{{ commons.imageinfo.0.thumbwidth }}"
             height="{{ commons.imageinfo.0.thumbheight }}"
             alt="{{ commons.labels.en.value|escape('html_attr') }}"
    <figcaption>{{ commons.labels.en.value }}</figcaption>

Note that this is also using the commons() Twig function, which is documented separately.

Example: Flickr

In any Markdown file:

{{{flickr id=123456}}}

In templates/shortcodes/flickr.html.twig:

{% set flickr = flickr(shortcode.attr('id')) %}

<figure itemscope itemtype="">
    <a href="{{ flickr.urls.photopage }}"><img alt="An image from Flickr." src="{{ flickr.urls.medium_image }}" /></a>
        <strong itemprop="name">{{ flickr.title }}{% if flickr.description %}:{% endif %}</strong>
        {% if flickr.description %}
            <span itemprop="description">{{ flickr.description|raw }}</span>
        {% endif %}
        <span class="meta">
            {% if flickr.dates.taken %}
                {% set date = date_create(flickr.dates.taken) %}
                <time datetime="{{ date.format('c') }}">{{ date.format('Y F j l, g:iA') }}</time>
            {% endif %}
            &middot; <a href="{{ flickr.urls.photopage }}">via Flickr</a>
            &middot; <a href="{{ flickr.license.url }}" rel="license" title="{{ }}">&copy;</a>