Sites in Dexy
How to Use the Website Reporter
Contents:
The WebsiteReporter
The WebsiteReporter helps you generate a website from your Dexy output. It helps you do things like apply HTML templates and automatically generate page navigation.
The WebsiteReporter won't run by default. You need to use the --reports
command line option to customize which reports dexy runs. If you are making a website, you will probably want the WebsiteReporter to run every time you run dexy, so instead of typing this on the command line each time, you can put it in a config file like this:
# YAML config file for dexy.
# Options are same as command line options, for more info run 'dexy help -on dexy'.
reports: 'ws run'
This means that only the WebsiteReporter and RunReporter will run, so you won't see the output/
and output-long/
directories you're used to. You can always add them to the list if you still want them. You can see a list of all the available reporters like this:
$ dexy reporters
ALIAS DIRECTORY INFO
long output-long Creates complete dexy output with files given long, unique filenames.
output output Creates canonical dexy output with files given short filenames.
run
ws output-site Applies a template to create a website from your dexy output.
The alias is what you add to the --reports list, which should be a string where each alias is separated by a space.
The WebsiteReporter will copy all non-HTML files to the output-site/
directory unchanged. When it encounters a HTML file, it will look to see if there is already a header and, if so, it will leave that file alone. If the HTML appears to be just internal page content, then the WebsiteReporter will look for a file named _template.html
and will apply that template.
Finding Templates
The WebsiteReporter looks first in the same directory as the file being processed, then it looks in each succeeding parent directory as far up as the project root, until it finds a file named _template.html
. It uses the first one it finds (i.e. the one closest to the HTML document being processed). If it does not find one, it raises a UserFeedback exception to let you know. You can tell the WebsiteReporter not to try to apply a template by setting the ws_template
argument to False, as in this example:
You can also specify another file to use as a template, as in this example:
docs:
- index.html|jinja|markdown|htmlsections:
- ws_template : '_home_template.html'
- .md|jinja|markdown:
- meta
- source
The content Tag
The templates are jinja templates. Here is a very simple template which only uses a single tag, content
, to insert the content of the page it is processing:
link to page rendered in template
If the page content is split into named sections, these sections can be referenced as attributes of content
.
For example, this HTML source is split into sections by the htmlsections
filter, and then the named sections are placed into the relevant spots in the template.
<!-- section "head" -->
<style type="text/css">
body { background-color: purple; }
</style>
<!-- section "body" -->
<p>This is the main content!</p>
link to page rendered in template
Here is the dexy.yaml
for these pages:
- simple_content.html:
- ws_template: _simple_template.html
- head_body_content.html|htmlsections:
- ws_template: _head_body_template.html
Jinja Templates and Macros
The WebsiteReporter lets you make use of jinja's template inheritance and macros. The dexy project root and the directory containing the page being processed are passed to jinja's FileSystemLoader, so you can reference templates and macro files relative to either of these locations.
For this website, we define a _base.html
template:
{% from 'macros/nav.jinja' import menu with context %}
<!DOCTYPE HTML>
<!--
Altitude: A responsive HTML5 website template by HTML5Templates.com
Released for free under the Creative Commons Attribution 3.0 license (html5templates.com/license)
Visit http://html5templates.com for more great templates or follow us on Twitter @HTML5T
-->
<html>
{% block head -%}
{% include 'macros/_header.html' -%}
{% endblock -%}
<body>
<div id="wrapper">
<div id="header-wrapper">
<header id="header">
<div class="5grid-layout">
<div id="menu">
<nav class="mobileUI-site-nav">
{% block nav_menu -%}
{{ menu() }}
{% endblock -%}
</nav>
</div>
</div>
{% block logo -%}
{% include 'macros/_logo.html' -%}
{% endblock -%}
</header>
</div>
{% block banner -%}
{% include 'macros/_banner.html' -%}
<div class="divider"></div>
{% endblock -%}
{% block mainpage -%}
<div id="page-wrapper">
{{ content }}
</div>
{% endblock -%}
</div>
{% block footer -%}
{% include 'macros/_footer.html' -%}
{% endblock -%}
</div>
</body>
</html>
We can break our layout into manageable sections by using jinja's include statements to insert snippets into our template, and by defining blocks we can use jinja's inheritance to customize these blocks in other templates. Here is our generic site-side _template.html
{% extends '_base.html' -%}
{% block banner -%}
{% endblock -%}
{% block mainpage -%}
<div id="page-wrapper">
<div class="divider"></div>
<div class="12u">
<div class="5grid-layout" id="onecolumn">
<div class="row">
<div class="12u">
<section>
<div class="post">
{{ content }}
</div>
</section>
</div>
</div>
</div>
</div>
</div>
{% endblock -%}
And here is a custom template for the home page:
{% extends '_base.html' -%}
{% block mainpage -%}
<div id="featured-content-wrapper">
<div class="12u" id="feature-content">
<div class="5grid-layout">
<div class="row">
{{ content.one }}
</div>
</div>
</div>
</div>
<div id="page-wrapper">
<div class="divider"></div>
<div class="12u">
<div class="5grid-layout" id="page">
<div class="row">
<div class="7u">
{{ content.two }}
</div>
<div class="1u"> </div>
<div class="2u" id="sidebar1">
{{ content.three }}
</div>
<div class="2u">
{{ content.four }}
</div>
</div>
</div>
</div>
</div>
{% endblock -%}
Navigation and Meta Goodies
In addition to referencing the page content of the page the template is being applied to, the WebsiteReporter also generates helpers for site navigation and similar utilities.
We can see this in the navigation menu macro:
{% macro menu() %}
<ul>
{% for dirname in sorted(navigation.directories[1]) -%}
{% set subdirs = navigation.directories[1][dirname] -%}
{% if navigation.current_index == dirname -%}
{% set liclass = 'active' -%}
{% else -%}
{% set liclass = '' -%}
{% endif -%}
<li class="{{ liclass }}"><a href="/{{ dirname }}">{{ dirname.capitalize() }}</a></li>
{% endfor -%}
{% endmacro %}
Here is a page showing all the objects which are available to WebsiteReporter templates: