How to blog with nanoc

This is a follow-up to “History of morr.cc”. I’d like to show you how this blog is created using the fantastic static site generator “nanoc”.

Why would you want static sites?

To be short: Simplicity, security, speed.

OK, how does it work?

You can look at this blog’s source code on GitHub.

• The content folder contains the blog posts, assets related to the layout (in assets), and some top-level pages and files. Texts are written in the Markdown format, a simple markup language that is even comfortable to read as plain text (for example, look at this post’s source). Each post has a header containing at least a title, the date of publication, and some tags in YAML format.

• The layouts folder contains some HTML templates with eRuby tags.

• The lib folder contains helper functions you can use in the eRuby tags and a custom filter that reformats HTML nicely using tidy-html5. More about that later.

This is all tied together by the Rules file, which contains several types of instructions. Files in the content directory are treated as items with an identifier that is the file’s path minus their filename extension. A file like content/how-to-blog-with-nanoc/index.md has the identifier /how-to-blog-with-nanoc/.

• compile statements say “for an item with this identifier, apply these filters (which evaluate eRuby tags, convert Markdown to HTML, and tidy the result) and layouts (which stuff the result into one of the layout files). Nanoc comes with some basic filters, but its easy to write your own, too.

• route statements say “for an item with this identifier, put the processed content here”.

• layout statements say “for a layout with this identifier, apply these filters.

• preprocess statements can be used to create new items, like pages for each tag, or to do some other preprocessing.

Now, when executing nanoc, all these rules are applied and the result is put in the output folder. nanoc deploy uploads this folder to my web server (the configuration for that is in nanoc.yaml. Very handy is nanoc aco, that starts a web server locally, lets you preview your site and autocompiles everything that is needed when refreshing a page.

And, that’s really everything.

Resources

nanoc.ws contains everything you need to know to build your own nanoc powered site. Have fun!

Comments?

Send a message to @blinry@chaos.social or drop me a mail at mail@blinry.org. Also, you can support me on Patreon or subscribe to my newsletter!