Templates

Engineer makes heavy use of Jinja2 templates to render a site. Most templates come as part of Themes, and you might not even need to worry about them. In fact, Engineer makes it easy to customize your site without creating full-blown Jinja templates.

Note

Doing anything somewhat advanced with templates will require some knowledge of the Jinja2 template syntax and features. The Jinja2 Documentation is an excellent place to learn more about the language. The Template Designer Documentation in particular is a useful starting point if you’re ready to jump right in. As usual, you can look at the sample site as a reference point to see how things fit together.

Template Fragments

Template fragments are blocks of HTML that you want to put into pages on your site. For example, the _footer.html fragment contains markup you want to appear in the footer of your site. While template fragments are complete Jinja2 templates, and thus can contain any Jinja2 syntax, you don’t have to. In fact, with the exception of Navigation, you can simply put raw HTML into your template fragments - Engineer will pull the content of those fragments into your site.

Built-in Template Fragments

Engineer makes several template fragments available to all sites. While individual themes might also expose their own, the following are available regardless of the theme you’re using. In order to ‘use’ a fragment, all you need to do is create a file with the same name as the fragment you’re using in your TEMPLATE_DIR. For example, creating a _footer.html file in your template directory will make Engineer put the contents of that file in the footer of your site.

Tip

Template fragments should always be put in your site’s TEMPLATE_DIR. The built-in fragments should all be in the root of the template dir, but themes might also support other fragments that should be located in slightly different places. Check your theme’s documentation for details.

By convention all template fragments’ names start with an underscore (_) and are optional. That said, the _sidebar.html and _nav_primary.html fragments should be created. Otherwise you’ll most likely see sample content for your site’s sidebar and navigation.

Theme Designer Note

Template fragments are meant to contain only HTML (with the notable exception of Navigation). If you’re including your own fragments, you should ensure users don’t need to use special Jinja syntax or unique macros in their fragments if at all possible. If you do require such advanced syntax, be sure it’s clearly documented.

_scripts_top.html
Use this fragment to put additional scripts at the top of your pages. This can be useful for getting web analytics scripts into your site, for example.
_scripts_bottom.html
This fragment is similar to _scripts_top.html except the scripts are included at the bottom of your pages rather than at the top.
_stylesheets.html
Use this fragment to put additional CSS or LESS stylesheets at the top of your pages.

_nav_primary.html

_nav_primary_links.html
These two fragments together contain the outer navigation links for your site. See the documentation on Navigation for more details on fragment and what they should contain.
_sidebar.html
This fragment contains a sidebar for your site. See the documentation on Sidebar for more details on this fragment and what it should contain.
_footer.html

This fragment contains the footer content for your site.

Note

The Engineer developers (just me, really) would really appreciate it if you linked to the Engineer project in your footer. If you’re finding Engineer useful, then linking back to the project is a great way to spread the word. You can put a link in manually if you’d like, or you can simply paste the following snippet into your _footer.html fragment:

{% include 'snippets/_powered_by.html' %}

That will insert a little ‘Powered by Engineer’ link into your footer. Don’t feel obligated to do this, of course, but if you do I really do appreciate it!

Sitemap Templates

If you need to customize the sitemap that Engineer generates for you, you can provide your own templates that Engineer will use to generate it. This template should be named sitemap.xml and should be in the root of your site’s TEMPLATE_DIR.

New in version 0.3.0.

Snippets

In addition to Template Fragments, some themes might provide ‘snippets’: small pieces of content or layout that you might want to include in your sidebar, footer, etc. For example, the Dark Rainbow theme provides snippets for a search bar and RSS feed links to include in your sidebar. Also, the ‘Powered by Engineer’ footer is a snippet. By convention, snippets are placed in the ‘snippets’ folder. Because some themes might not provide snippets, you should use the ignore missing command when including them in your site. For example:

<section>
    <p>Welcome to the Engineer sample site.</p>
    <hr/>
    <nav>
        <ul>
            <li><a href="{{ urlname('about') }}">about</a></li>
            <li><a href="{{ urlname('themes') }}">themes</a></li>
        </ul>
    </nav>
</section>

{% include 'snippets/_search.html' ignore missing %}
{% include 'snippets/_feed_links.html' ignore missing %}

New in version 0.4.0.

Template Pages

Many sites have a need for ‘flat’ pages like an ‘about’ or ‘contact us’ page. The ‘flat’ terminology isn’t quite right in Engineer’s case, since all pages in Engineer are flat, but the need is real. Engineer provides this capability via template pages.

A template page is basically just a simple HTML page in your site, but unlike a standard HTML page, you can use Jinja2 templates to inherit the look and feel of your site but add content specific to your page. As usual, it’s easier to look at an example. Here’s the themes.html template page from the Engineer sample site:

{% extends 'theme/template_page_simple.html' %}

{% block page_title %}Themes{% endblock %}

{% block header_secondary_title %}Themes{% endblock %}

{% block content %}
    <article>
        <p>Engineer comes with two themes, and provides a basic framework for creating
        additional ones if you're so inclined.</p>

        <h2>Dark Rainbow</h2>

        <p>The default Engineer theme, Dark Rainbow has also been called 'Voldemort's Skittles,'
            'Unicorn Vomit,' and other names not fit to repeat here. Needless to say, the parade of
            colors isn't for everyone.</p>
    </article>
{% endblock %}

As you can see, this page extends theme/template_page_simple.html, which is one of the inheritable templates included with the Dark Rainbow theme. It sets the page title to ‘Themes’ and adds some basic content for the page in the content block.

All themes include a basic template page base called template_page_base.html that exposes the following blocks:

page_title
The title of the page.
content
The content of the page.

Themes may expose their own additional template page bases, like Dark Rainbow does, but at the very least template_page_base.html will always be available.

Template pages should be placed in your TEMPLATE_PAGE_DIR. Folders are permitted, so you can organize your template pages and that structure will be reflected in the URL paths to your pages.

Tip

If you’d like to write content for template pages in Markdown, you can. Simply wrap your Markdown content with the markdown filter. For example:

{% filter markdown %}
    This site is built using [Engineer](/projects/engineer), a static site generator I wrote myself after
    being inspired by [Brent Simmons][], Marco Arment's Second Crack, Jekyll, Octopress,
    and Hyde. It's written in [Python][] and uses [Jinja2][] for templating. I use the management site
    available with Engineer (aka Emma) to manage my posts, which in turn runs on [Bottle][].
{%endfilter %}