{"00000:1": "
<h2 class="title">Sites in Dexy</h2>\n\n<p class="subtitle">How to Use the Website Reporter</p>\n\nContents:\n\n[TOC]\n\n### The WebsiteReporter\n\nThe WebsiteReporter helps you generate a website from your Dexy output. It\nhelps you do things like apply HTML templates and automatically generate page\nnavigation.\n\nThe 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:\n\n{{ d['/dexy.conf|pyg'] }}\n\nThis 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:\n\n{{ d['/list-reports.sh|shint|pyg'] }}\n\nThe alias is what you add to the --reports list, which should be a string where each alias is separated by a space.\n\nThe 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.\n\n### Finding Templates\n\nThe 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:\n\n{{ d['/dexy.yaml|idio']['source'] }}\n\nYou can also specify another file to use as a template, as in this example:\n\n{{ d['/dexy.yaml|idio']['docs'] }}\n\n### The content Tag\n\nThe 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:\n\n{{ d['_simple_template.html|pyg'] }}\n\n{{ d['simple_content.html|pyg'] }} [link to page rendered in template](simple_content.html)\n\nIf the page content is split into named sections, these sections can be referenced as attributes of `content`.\n\n{{ d['_head_body_template.html|pyg'] }}\n\nFor 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.\n\n{{ d['head_body_content.html|pyg'] }} [link to page rendered in template](head_body_content.html)\n\nHere is the `dexy.yaml` for these pages:\n\n{{ d['dexy.yaml|idio']['content-demos'] }}\n\n### Jinja Templates and Macros\n\nThe WebsiteReporter lets you make use of jinja's [template inheritance](http://jinja.pocoo.org/docs/templates/#template-inheritance) and [macros](http://jinja.pocoo.org/docs/templates/#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.\n\nFor this website, we define a `_base.html` template:\n\n{{ d['/_base.html|pyg'] }}\n\nWe 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`\n\n{{ d['/_template.html|pyg'] }}\n\nAnd here is a custom template for the home page:\n\n{{ d['/_home_template.html|pyg'] }}\n\n### Navigation and Meta Goodies\n\nIn 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.\n\nWe can see this in the navigation menu macro:\n\n{{ d['/macros/nav.jinja|pyg'] }}\n\nHere is a page showing all the objects which are available to WebsiteReporter templates:\n\n[link to page which introspects on other stuff](introspect.html)\n
\n"}