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!
Sidebar¶
The _sidebar.html
should contain HTML markup you wish to display in a sidebar on your site. This content
should be wrapped in a <section>
container as appropriate. For example, the sample site _sidebar.html
looks like this:
<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 %}
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 %}