site generation

the pipeline

During site generation, each file is processed and the result is placed in the corresponding path in the output folder. Thus, the directory structure of your project is the directory structure of your site. You can change this behavior via routing.

Files are processed as follows:

The local template is the template.tmpl file in the current directory, or if that doesn't exist, the shallowest parent directory. The master template is the file meta/master.tmpl. See templates. The result is outputted as a .html file in its corresponding position in the output folder.

Note that .md files (without the "+") are escaped, so all double braces {{ }} will show up literally in the output. Use a plain .md file when you don't want to trigger the template engine for that file.

Note that files in the meta/ and output/ directories do not go through the pipeline.


Routing can be used to give files a custom output path. Add an entry called "routes" to meta.json:

"routes": {
  "[old-prefix-1]": "[new-prefix-1]",

Paths starting with [old-prefix-X] will have this prefix replaced with [new-prefix-X] in the output folder. The paths are given relative to the site top, with no leading slash. For example: "pages/": "/" will cause all files in the pages/ directory to be copied to the top level of the output folder.

example directory structure

- Input -             -->         - Output -
site/                             site/
  index.html+                       index.html
  archive.html+                     archive.html
  pages/                          pages/
    life/                           life/                     funstuff.html
    work/                           work/
      template.tmpl                     meetings.html
  posts/                          posts/
    template.tmpl                       hello.html                 codesamples.html

the context

Each templated file gets its own context, a set of variables that it can access. The context contains:


Templates are templated HTML files that take as input other unformatted HTML or Markdown files. Templates can be used to define a common layout for all files in a directory. For example, a template in your posts/ directory could be used to format all blog posts with their date, title and content.

During site generation, each file is compiled against its local template (a file called template.tmpl in the file's directory, or if it doesn't exist, in the shallowest parent directory). Then, that output is compiled against the master template, meta/master.tmpl (see master.tmpl).

When a file is compiled against a template, a variable called content is created, with the (HTML) contents of the file as its value. Thus, the template has access to the input file through the template call, {{{ content }}}, as well as the rest of the file's context.


Here is a "blog post" template. If you save it as template.tmpl in a directory called posts, it will format each post file in posts/ with a date and title header:

  <small>{{ formatDate date }}</small>
  <div>{{ title }}</div>
    {{{ content }}}

(This requires the date package: use nanosite import date)

key files

meta/ is used to define macros that call Python functions. Code in this file has access to two special functions:



meta/master.tmpl is the final template all content files go through. Thus, it should contain your <html> </html> tags and other global tags. You can also declare global macros via the #macro tag.


<!DOCTYPE html>
    <title>{{ site.title }}</title>
    {{{ content }}}


meta/meta.json contains global variable declarations. Every key in the .json file will become a variable in the global context.

The site.url entry has a convenience feature attached: the development server changes site.url references to localhost references, so that you can work on an entirely local version of your site.


  "site": {
    "author": "Author",
    "tagline": "Tagline",
    "title": "Title",
    "url": ""
  "routes": {


meta/publish (meta/publish.bat on Windows) contains your custom publish script. Calling nanosite publish will run this script. You can create a script that best fits your workflow.


Publishing to GitHub Pages; this assumes you've set up a Git repository in your output/ folder, and created a GitHub Pages site with this repository.

nanosite clean
nanosite build

pushd output
git add .
git commit -m "autopublish"
git push origin master