On maintaining webgen
Why I still maintain my static website generator webgen
My static website generator webgen has been around for a long time. Though there are now many other static website generators written in Ruby, I still maintain webgen because some of its functionality is unique.
Development of webgen started 16 years ago, back in 2003 because I needed a tool for creating my personal website. From there it grew into a full-blown static website generator over the years (you can read more about its history at the webgen homepage). It had its heyday around 2007/2008 when not many static website generators existed (Hobix anyone?). A few years later the “boom years” for static website generators started and many, many were created. Ruby lends itself especially well for such a tool due to its rich ecosystem of web related libraries.
Nowadays webgen is probably only used by a handful of people besides myself; if you are one them, I would love to hear why you are sticking with webgen. I still maintain webgen and generate all my websites with it, like this personal website, the webgen homepage, the cmdparse homepage, the kramdown homepage or the HexaPDF homepage.
One reason is that I’m naturally very familiar with it, it works great and is reasonably fast. However, the main reason is that it provides some unique features that I didn’t find anywhere else. Here are two that I find especially useful:
- Flexible file system layout
-
In contrast to most other static website generators webgen doesn’t prescribe a certain directory structure. The default is the following:
website/ # your website directory webgen.config # webgen's configuration file src/ # the directory with all the source files ext/ # extensions to webgen's functionality out/ # where all the generated files go tmp/ # directory for temporary files and caches
However, the only thing webgen really needs is the
webgen.config
file, which can be a YAML or Ruby file and configures webgen. cmdparse, for example, uses the following in itswebgen.config
file:website.config['sources'] =[['/', :file_system, 'doc']] website.config['destination'] = [:file_system, 'htmldoc'] website.config['website.tmpdir'] = 'webgen-tmp'
This means that the source directory is changed to
doc/
, the output directory tohtmldoc/
and the temporary directory towebgen-tmp/
. Due to this flexibility it is easy to ship the source for the documentation website with the code itself. - RDoc integration
-
webgen can integrate the API documentation created via RDoc into a website. This means, for example, that the API documentation has the same look and feel as the rest of the documentation (see, for example, the documentation for CmdParse::CommandParser).
What is more important, though, and more useful is that the other parts of the website can easily link to any part of the API documentation. This functionality is extensively used by the webgen homepage itself and, for example, by the HexaPDF homepage.
Taking the HexaPDF changelog as example, you will find that all mentions of classes or methods are linked to the correct place. There will be no dangling links because during the generation of the website all such links are automatically checked and a warning would appear if a link target is not found.
The only other tool I know that integrates API documentation in such a way is Sphinx. But maybe Antora (project documentation tool based on Asciidoctor) will get such a functionality, too!
Until another tool provides at least these two functionalities, I guess I will maintain webgen. The time and effort is not that much and if I need something new I can quickly implement it.