nanogen 0.9.9

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 $HOME:

$> 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. When this command completes, the blog directory will look like this:

~/blog
|-- _posts
`-- _layout

These are all the only two folders required by nanogen, and cannot currently be changed by the user. Your individual posts will go in the _posts directory, and the templates will go in the _layouts directory.

At this time, nanogen does not come with a built-in theme, so it’s up to the user to create their own.

Creating Posts

One way to create new posts is by creating a new file in the _posts directory. The filename is important and must match the following rules:

1. The file can’t start with an underscore (they are ignored)

2. The file’s name must match the pattern yyyy-mm-dd-<post_title_slug>

3. The file’s extension must be a valid Markdown extension (md, mdown, or markdown).

To illustrate:

# valid filename
2015-11-01-this-charming-man.md

# invalid filename
15-11-1-bigmouth-strikes-again.txt

If you don’t want to try to remember all that, you can use nanogen’s new command to do it for you. The only required argument to this command is the title of the post being generated:

$> nanogen new "Example Post Title"

Running this will create a properly-named and formatted file in the _posts directory.

Draft posts aren’t an “official” feature of nanogen, however they are possible. By default, when nanogen generates a site it will only look in the _posts folder for files to process. If you’d like to maintain drafts of your posts before you publish them, you can create a _drafts folder next to the _posts folder and nanogen will ignore it during site generation. Alternatively, you can prepend the filename of a drafe with an underscore, and nanogen will skip over it when searching for files to process.

## This will become the title (with hashes stripped out)

**This** will become the post's _content_.

Generating Your Site

Once you’re ready to generate your site, you can use the build command:

$> nanogen build

This command will walk your _posts directory, process any valid files it finds, and will write all the generated HTML files into a _site folder. Although you will want to preview this on your local development system (see the following section for how to do this), the _site folder can be uploaded to your web host as-is.

Note: before each build nanogen will run the clean command. clean will remove the _site directory and all of its contents, so it’s not a good idea to add anything to the _site directory that you intend to keep between builds.

Previewing Your Site

To see what your site will look like before you upload it to a live webserver for the world to see, nanogen provides a built-in server that allows you to preview your generated site:

$> nanogen preview

This command will start a server that listens on localhost port 8080. Simply open http://localhost:8080 in a web broswer to see how your site looks. If you’d like to use a different hostname or port, nanogen provides an option for each (-h|--host, and -p|--port, respectively). The following example will start a server that listens on local.dev port 8000 (http://local.dev:8000):

$> nanogen preview --host local.dev --port 8000

Cleaning

If your _site folder somehow gets corrupted, or you’d simply like to generate your site from scratch, you can use the clean command:

$> nanogen clean

There is no undo or confirmation when running this command.

Template Files

The templates that make up the theme for your nanogen blog need to be placed in the _layout directory. nanogen only expects a few files to exist, and those files are:

1. index.html

2. post.html

3. rss.xml

index.html will be used as the sites homepage, post.html will be used to generate each individual post, and rss.xml will be be used to generate your blog’s RSS feed.

All of your blog’s posts will be passed to index.html and rss.xml via a Jinja2 context variable named posts. Individual posts will be passed to post.html via a context variable named post. Each post will have the following relevant attributes available to use in the template:

• content - the HTML content of the post

• title - the title of the post (will not be processed as Markdown)

• pub_date - a Python datetime object representing the publish date of the post

• permalink - the relative URL to the post

Please see the _layout directory in the included example for a basic theme you can use to as a jumping off point for your own theme.

Static Files

If you have any files that you’d like to include in the published site (JavaScript files, CSS files, images, etc), place them into a folder named static inside the _layout folder. This folder will automatically be copied into the _site folder during the build process. No processing will be performed on the files within the static directory.