Package: nanogen
nanogenA very small static blog generator written in Python.Purposenanogenexists solely so I can have a blogging platform I call my own.
The platform is very intentionally bare bones and simple. The code is
intentionally utilitarian and realistically less-than-perfect.If you have an idea for a way to improve this without significantly increasingnanogen’s complexity, please open an issue and let me know.If you’re looking for a more fully-featured static site generator, may I
recommend something likeJekyllorPelican?InstallationThe best way to installnanogenis throughpip:$> pip install nanogenIf you don’t want to install it viapip, you can install it
manually:$> git clone https://github.com/epochblue/nanogen
$> cd nanogen
$> python setup.py installNote : To avoid possible dependency version issues, I recommend installingnanogeninto a virtual environment, rather than globally.How To UseInitializingOncenanogenis installed, navigate to the directory you’d like to
use as your new blog. Our examples will use ablogdirectory in$HOME:$> mkdir blog
$> cd blogOnce there, runnanogen’sinitcommand to get started:$> nanogen initRunning this command will generate the basic directories used bynanogen. When this command completes, theblogdirectory will
look like this:~/blog
|-- _layout
|   `-- blog.cfg
`-- _posts_postsand_layoutare the only two folders required bynanogen, and
their names cannot be changed by the user. Your individual posts will go in the_postsdirectory, and the templates will go in the_layoutsdirectory.Theblog.cfgfile will hold metadata about your blog (author’s name and
email, along with the site’s title, description, and URL). A skeleton version of
this file is created for your duringinit. The keys and values contained in
this file will be passed to your templates under thesitevariable. For
example: your site’s title will be be available in thesite.titleattribute.At this time,nanogendoes not come with a built-in theme, so it’s up to
you to create your own.Creating PostsOne way to create new posts is by creating a new file in the_postsdirectory. The filename is important and must match the following rules:The file can’t start with an underscore (they are ignored)The file’s name must match the patternyyyy-mm-dd-<post_title_slug>The file’s extension must be a valid Markdown extension (md,mdown, ormarkdown).To illustrate:# valid filename
2015-11-01-this-charming-man.md

# invalid filename
15-11-1-bigmouth-strikes-again.txtIf you don’t want to try to remember all that, you can usenanogen’snewcommand 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_postsdirectory.Draft posts aren’t an “official” feature ofnanogen, however they are
possible. By default, whennanogengenerates a site it will only look in the_postsfolder for files to process. If you’d like to maintain drafts of your
posts before you publish them, you can create a_draftsfolder next to the_postsfolder andnanogenwill ignore it during site generation.
Alternatively, you can prepend the filename of a draft post with an underscore,
andnanogenwill skip over it when searching for files to process.Post Content Formatnanogenposts don’t useYAMLfront-matter, so the first line of your post
will be used for the title of the post. The content of the posts will be
processed asMarkdown(the Github-flavored variety, complete with
syntax-highlighted code blocks). A minimal example of a validnanogenpost
is this:## This will become the title (with hashes stripped out)

**This** will become the post's _content_.The title will be stripped out of the post’s content, though it will be
available to your themes via thepost.titleattribute.Generating Your SiteOnce you’re ready to generate your site, you can use thebuildcommand:$> nanogen buildThis command will walk your_postsdirectory, process any valid files it
finds, and will write all the generated HTML files into a_sitefolder.
Although you will want to preview this on your local development
system (see the following section for how to do this), the_sitefolder can be uploaded to your web host as-is.Previewing Your SiteTo see what your site will look likebeforeyou upload it to a live
webserver for the world to see,nanogenprovides a built-in server
that allows you to preview your generated site:$> nanogen previewThis command will start a server that listens onlocalhostport8080. Simply openhttp://localhost:8080in a web broswer to
see how your site looks. If you’d like to use a different hostname or
port,nanogenprovides an option for each (-h|--host,and-p|--port, respectively). The following example will start a server
that listens onlocal.devport8000(http://local.dev:8000):$> nanogen preview --host local.dev --port 8000CleaningIf your_sitefolder somehow gets corrupted, or you’d simply like
to generate your site from scratch, you can use thecleancommand:$> nanogen cleanThere is no undo or confirmation when running this command.nanogenThemesNote:nanogendoesn’t provide any themes out of the box. If you’d like to
develop your own theme fornanogen, this section should explain how.nanogenusesJinja2for its templating. If you need information
about Jinja’s syntax, pleaserefer to their documentation.Template FilesThe templates that make up the theme for yournanogenblog need to be placed
in the_layoutdirectory.nanogenonly expects a few files to exist, and
those files are:index.htmlpost.htmlrss.xmlindex.htmlwill be used as the sites homepage,post.htmlwill be used to
generate each individual post, andrss.xmlwill be be used to generate your
blog’s RSS feed.All of your blog’s posts will be passed toindex.htmlandrss.xmlvia aJinja2context variable namedposts(posts will be in reverse
chronological order). Individual posts will be passed topost.htmlvia a
context variable namedpost. Each post will have the following relevant
attributes available to use in the template:html_content- the HTML version of the postmarkdown_content- the Markdown version of the post (minus the title)title- the title of the post (will not be processed as Markdown)pub_date- a Python datetime object representing the publish date of the postpermalink- the relative URL to the postPlease see the_layoutdirectory in the included example for a basic theme
you can use to as a jumping off point for your own theme.Static FilesIf 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 namedstaticinside the_layoutfolder. This folder will automatically be
copied into the_sitefolder during the build process. No processing will
be performed on the files within thestaticdirectory.Sites Usingnanogenhttp://blog.cubicle17.com/(code isavailable here)Licensenanogenis MIT licensed. Please see includedLICENSEfile for
more information.AuthorBill Israel-bill.israel@gmail.com