content/articles/creating-smart-static-sites-with-nanoc.textile
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
----- :type: article :tags: - website - ruby - programming - writing :date: 2009-09-15 13:32:51.049000 +02:00 :permalink: creating-smart-static-sites-with-nanoc :title: "Creating Smart Static Sites with nanoc" :toc: true ----- Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly knew HTML and CSS, nevermind server-side languages, so I remember creating a _pseudo-template_ for the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change in all the pages of the site – the whole eight of them. Five years later, after rebuilding this web site "seven times":/h3rald/ using different backends (PHP + CakePHP, Ruby + Rails +Typo, etc.), I decided to make it static again, this time with a twist. It all started when I read a "post":http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html by Tom Preston-Warned that I finally decided to give it a try, and today, the 8th release of this web site is 100% static: if you load any page, there's no server-side interpretation going on, you're just browsing a plain HTML page, at most with a few AJAX calls. But let's start from the beginning. h3. Why I don't need a blogging platform There's nothing wrong with blogging platforms like Wordpress: they allow _anyone_ to publish content on the web using a user-friendly administration area. They were built with one thing in mind: make publishing content on the web something as simple as possible, even for people who don't know anything about HTML, let alone server-side scripting. What about people who _do_ know about web development though? Do they still need a blogging platform? Depends. If you are comfortable with editing files using a text editor, if you enjoy using the command-line on a daily basis, if like programming and _hacking_ a little bit, if you don't really care about fancy and user-friendly administration backends... _then you probably don't_. All you need is a system to transform a bunch of source files into a web site. The good news is that such system exists – and you're also spoiled for choices! h3. Introducing Site Compilers The first _site compiler_ I discovered was "Webby":http://webby.rubyforge.org/: bq. [...] Webby works by combining the contents of a page with a layout to produce HTML. The layout contains everything common to all the pages — HTML headers, navigation menu, footer, etc. — and the page contains just the information for that page. You can use your favorite markup language to write your pages; Webby supports quite a few. There are quite a few applications like Webby, such as: * "nanoc":http://nanoc.stoneship.org/ * "Rassmalog":http://snk.tuxfamily.org/lib/rassmalog/doc/guide.html * "Jeckyll":http://www.jekyllrb.com/ * "WebGen":http://webgen.rubyforge.org/ * "Rog":http://rog.rubyforge.org/ * "Rote":http://rote.rubyforge.org/ * "Hobix":http://hobix.com/ * "RakeWeb":http://rakeweb.rubyforge.org/wiki/wiki.pl * "RubyFrontier":http://www.apeth.com/RubyFrontierDocs/default.html * "StaticMatic":http://staticmatic.rubyforge.org/ * "StaticWeb":http://staticweb.rubyforge.org/ * "ZenWeb":http://www.zenspider.com/ZSS/Products/ZenWeb/ * "YurtCMS":http://yurtcms.roberthahn.ca/ * "NanoBlogger":http://nanoblogger.sourceforge.net/ There are probably even more, with different features, but they all try to solve the same problem: provide a way to generate static web sites in an automated way. I spent some time reading about each one of them, "evaluating the pros and cons":http://github.com/h3rald/h3rald/issues/closed#issue/1 and in the end I decided to go for "nanoc":http://nanoc.stoneship.org/, simply because it was the only one that seemed to fit all my needs. h3. A quick overview of nanoc nanoc (*nano* *c*ompiler) is a nifty tool written in Ruby suitable for _[...] building small to medium-sized websites_. In other words, anything which doesn't involve some fancy user interaction. For what concerns blogs, the only user interaction is _comments_ – but that's fine, because there's more than one web service for that, such as "Disqus":http://disqus.com/ or "IntenseDebate":http://intensedebate.com/. h4. Some details on the project Compared to the alternatives, nanoc is one of the most mature and most maintained, having hit just a few weeks ago its 3.0 release. Its creator, Denis Defreyne, uses it for his own "web site":http://stoneship.org/ and is involved with the project on a daily basis, both coding and offering support to nanoc users like myself who regularly ask questions on the "nanoc user group":http://groups.google.com/group/nanoc. Denis also seems very concerned about keeping documentation up-to-date – something that really impressed me from a technical writer's point of view. The "tutorial":http://nanoc.stoneship.org/tutorial/ he put together will get you started in no time, and the "manual":http://nanoc.stoneship.org/manual/ will explain everything else you may possibly want to know. When release 3.0 came out he even put together a "migration guide":http://nanoc.stoneship.org/migrating/. If this is still not enough and you don't mind spending some time extending the system, nanoc's "RDoc documentation":http://nanoc.stoneship.org/doc/3.0.0/ is very comprehensive compared to other Ruby projects. h4. Sites, Items and data sources Nanoc ships with a really neat command line tool that can do most of the work for you. @nanoc3 create_site h3rald@ will create a new web site in a folder called h3rald. The contents of this folder are laid out according to a particular logic (_convention over configuration_, remember?) So: !>/img/nanoc/structure.png! ##################### * *content* – your articles, pages, stylesheets, images, ...all the site content and assets. * *layouts* – the site layouts (and partial layouts) * *lib* – place your custom ruby code and vendor libraries here * *output* – your "compiled" site, ready to be deployed * *config.yaml* – your site's configuration file. The only one (and it's just a few lines) * *Rakefile* – place any custom Rake task here * *Rules* – defines the rules for compilation, layout and routing Here's the default @config.yaml@ file: <% highlight :yaml do %> --- data_sources: - items_root: / layouts_root: / type: filesystem_compact output_dir: output <% end %> A _data source_ in Nanoc defines where data is retrieved from to create the web site. By default, the "filesystem_compact":http://nanoc.stoneship.org/doc/3.0.0/Nanoc3/DataSources/FilesystemCompact.html data source requires that you create two files in the /content folder for each article or page of your web page: * One containing the actual content of the page * Another for the page's arbitrary metadata By personal preference, I chose the "filesystem_combined":http://nanoc.stoneship.org/doc/3.0.0/Nanoc3/DataSources/FilesystemCombined.html data source, which allows you to combine the content and the metadata of a page in a single file. The source code for this very article, for example, starts like this: <code> ----- :type: article :tags: - website - ruby - programming - writing :date: 2009-09-15 13:32:51.049000 +02:00 :permalink: creating-smart-static-sites-with-nanoc :title: "Creating Smart Static Sites with nanoc" :toc: true ----- Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly knew HTML and CSS, nevermind server-side languages, so I remember creating a _pseudo-template_ for the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change in all the pages of the site – the whole eight of them. </code> At run time, the content goes through a Textile filter and the metadata is used in layouts, to generate tag links automatically, for example. h4. Layouts, filters, and helpers h4. Rules and tasks h3. Migrating from your blogging platform h4. Posts and pages h4. Tags h4. 3rd-party services h3. Conclusion h4. Advantages h4. Disadvantages |