A very small static site generator
Project description
A very small static site generator written in Python.
Installation
The best way to install nanogen is through pip:
$> pip install nanogen
If you don’t want to install it via pip, you can install it by hand:
$> git clone https://github.com/epochblue/nanogen $> cd nanogen $> python setup.py install
Note : To avoid possible dependency version issues, I advise installing nanogen into a virtual environment, rather than installing it globally.
How To Use
Initializing
Once nanogen is installed, navigate to the directory you’d like to use as your new blog. Our examples will use a blog directory in our home directory:
$> mkdir blog $> cd blog
Once there, run nanogen’s init command to get started:
$> nanogen init
Running this command will generate the basic directories used by nanogen to build your static site. When this command completes, your blog directory will look like this:
~/blog |-- _posts `-- _layouts
These are all the only two folders required by nanogen, and cannot currently be changed by the user. If you’re creating a blog-style site, your individual posts will go in the _posts directory, and your site’s templates will go in the _layouts directory.
Publishing Posts
For nanogen to “publish” your posts, two things must be true:
they must be located in the _posts directory, and
they must be named like this: <year>-<month>-<day>-<name>.<ext>
<year> is a 4-digit year; <day> and <month> are two-digits
the <ext> must be a valid Markdown extension: md, mdown, markdown
Files in this folder that don’t match the above pattern will be skipped and will not be part of the generated site. The content of the post files follows the somewhat-standard format of YAML front- matter followed by a Markdown body. Below is an example of what this format looks like:
---- title: This is an example blog post slug: example-post layout: post.html ---- Everything from this point forward will be process as **Markdown**. You can _format_ your text however you please. Please check out the Markdown Documentation if you're unfamiliar with Markdown syntax.
The only required field in the front-matter is title. Two optional fields are slug and layout. If these aren’t present, defaults will be used. slug defaults to the <name> field in the post’s filename, and layout defaults to article.html. Any other fields you add to the front-matter will be ignored by nanogen, but are passed to and can be used by your templates.
Files in _posts will be “published” into folders based on the date in their filename, which is assumed to be their publish date. For example, a blog post with the filename 2014-11-08-example-post.html will be processed into a date-specific folder: site/<year>/<month>/<name>.html.
Draft posts aren’t an official feature of nanogen, however they are possible. By default, when nanogen generates a site it ignores any directories and files that start with a _ or a .. If you’d like to maintain drafts of your posts, you can create a _drafts folder and nanogen will dutifully ignore it during site generation.
Publishing Non-Post Content
For pages that aren’t intended to be blog posts (An index page, a post archive, About pages, Contact pages, etc), nanogen will simply pick them up as it processes files and folders. These files don’t use the front-matter/Markdown format, but are instead treated as raw templates. Their location relative to the root folder will determine their placement in the published site folder.
Static Files
If you have any files that you’d like to include in the published site you can use the keep field in the site configuration. Common uses for this would be CSS or JavaScript files that you need to help render the final site. See theConfiguration section for more information.
Building
Once you’re ready to generate your site, you can use the build command:
$> nanogen build
This command will walk your directory, process any valid files it finds, and will write all the generated files into a _site folder. Although you will want to check this on your local development system, the _site folder can be uploaded to your web host as-is and served as the root for your web server.
Note: before each build nanogen will reset the _site directory, so it’s not a good idea to add anything to the _site directory that you intend to keep between builds.
Cleaning
nanogen provides a clean command to remove your site folder if it somehow gets corrupted or you would like to generate your site from scratch:
$> nanogen clean
Configuration
In addition to the per-post configuration (front-matter), there is also a site-wide level of configuration available to all posts and templates. This configuration is stored in config.yaml in the project root. It isn’t strictly required, but nanogen will warn you if it doesn’t find one. Below is an example of a typical config.yaml file:
title: cubicle17 author: Bill Israel url: http://cubicle17.com/ keep: [static, css, js]
None of the fields in config.yaml are required, but anything defined will be passed to all templates. In the templates, anything defined in this file will be available under a special variable called site. For example, to use the url variable from the above example, use {{ site.url }} in your template.
keep is the only key in the configuration file that nanogen explicitly looks for. If it’s found, nanogen expects it to be a YAML list of directories (relative to the project’s root dir) that need to be copied into the generated site structure.
Templates
nanogen uses Jinja2 for its templating. If you need information about how Jinja templates work, please refer to their documentation.
nanogen passes a few things to each template, however. To single- post pages it passes the site-wide configuration under a variable called site, as well as all the information about the single post via a variable called post. To all other templates nanogen again passes the site-wide configuration under the site variable, as well as a list of all posts under a variable called posts.
Misc Notes
nanogen doesn’t provide a watch mechanism found in other static site generators. If you’d like this functionality, you can use a tool like Watchman or simply run build in an infinite loop. The following example will run a build every second:
$> while [ 1 ]; do nanogen build; sleep 1; done
License
nanogen is MIT licensed. Please see included LICENSE file for more information.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.