It was never my goal to write yet another static site generator. I would have preferred to simply use a good open-source solution. Yet eventually I wrote Urubu. Here is why.

I thought that the requirements that I had for my project sites were straightforward: it should be possible to write a manual, a blog, a faq, a news stream, and perhaps other kind of content, and integrate all those components seamlessly. But when I looked around, literally for years, I never found a suitable solution.

Consider a manual. It is typically not possible to write the manual for a static site generator with the tool itself. For example, the manual for Pelican, the market leader in the Python world, is written on Read the Docs. Isn't that remarkable? You go through the effort to write a static site generator, but to document it you need another static site generator. Well, not so with Urubu. The Urubu manual is an integral part of the website, and written with Urubu itself.

The problem is that most static site generators are blog-oriented. I have blogged about this before in I don't like blogs (Introducing Urubu). (The title is an exaggeration that reflects my frustration at the time.) Interestingly, there are also tools such as MkDocs, which are for manual-type content only. Which raises the inverse question: where is the faq? And the blog? And the news? The bottom line is that static site generators are not flexible enough to support different kinds of content. Urubu is the exception.

Another flaw of many static site generators is the irritating assertion that they are "simple". If you look at the overview in StaticGen, it seems like a competition in "simpleness". But look, I don't want "simple" tools. Nothing of value is "simple". What I am doing has some degree of sophistication, and I understand it requires effort from my part. Moreover, it is a big lie. None of those tools are trivial, as anyone who starts using them will find out. Telling a struggling new user that it is actually "simple" is an insult to her intelligence.

The most absurd example is Nikola. Here you are explicitly advised not to read the manual. If you need to read it, the designer states that he "failed". To me, that is nonsense. I put a lot of effort in the Urubu manual to explain concepts and usage as clearly as possible, because I believe that information is essential to use the tool efficiently. Therefore, if you don't use the manual and find yourself unnecessarily struggling as a result, I think you failed.

Urubu is not simple, but I believe it is intuitive, unlike the alternatives. The basic reason is the project organization: the built website matches the project directory structure exactly. What can be more intuitive than organizing a website as as directory? When you have subdirectories like manual/, faq/ and blog/ I believe it is clear what is inside them. That is much more intuitive than an arbitrarily imposed partitioning into "pages" and "posts", and "categories" to define meaning.

With that organization, many things fall into place. Need nice urls? Just use nice filenames. Index files are used to specify the content of a subdirectory, which is their original purpose. Need a blog or news stream? Specify reverse order by date. A manual or a faq? List the content explicitly. Alphabetic order of items? Specify order by title. And so on: order by any key, including user-defined keys.

Moreover, this organization enables Urubu's killer feature. If the project directory matches the site structure, you can easily refer to other pages. Urubu resolves Markdown reference links to other pages in the project, just like wiki links. For example, to refer to the blog post mentioned earlier, I use [i-dont-like-blogs] in the Markdown source. Urubu will resolve it and automatically use the page title as the link text.

To summarize: Urubu fixes the flaws of alternatives through unique features. It is not just for blogs, but for any type of content. It supports this by an intuitive organization that offers full flexibility and lets you easily refer to other project pages.