What my website was like before I chose Urubu as a static website generator—and why I chose Urubu.
Urubu is a static website generator: it lets you move the content of your website (the words) out of the HTML and into separate files called markdown, while the display of your website (the way the words are formatted and arranged on the page) remains in just a few HTML pages that can be reused over and over.
Where I Began
Before turning to Urubu for help, I had a static website of about 350 MB consisting of a little over 700 pages. I'd begun the site with a free CSS template, and written all the HTML, sometimes in Eclipse, and sometimes with the Geany text editor.
Other people often complain about having to write content in HTML, but I never minded. What bothered me was having exactly the same HTML code on more than one page. As a professional software developer, I knew that repeating the HTML on every page was breaking the DRY (Don't Repeat Yourself) principle. And as I filled out my website, I paid the price for breaking the principle whenever I wanted to modify the sidebar shared by the several pages in a group, not to mention the general banner shared by all of my pages. When the new year came and passed, I stopped updating the copyright in the footer of the pages. Too much work.
A second problem with the site was that there was no way to make room for reader comment on my website, and no way to do a search. I had no database associated with the site.
A final consideration: my time was limited. I had a full-time job, of course, but I also had a lot of interests as well as family obligations. Any migration of my website was going to have to be done in, at most, about five hours a week.
The Search for a Better Way
WordPress: Not Enough Control
I read up a little on Word Press, and even did a trial page or two. But, for a programmer like myself, it seemed to offer little control over how the content on a page was displayed. Porting my current layout—which I was quite fond of—would have been a royal pain.
Django: Too Much To Learn
I next turned to Django. This offered the fringe benefit of giving me more experience with Python. Perhaps one day I'd even be able to put Django on my resume.
But Django forced me to do an awful lot for the limited functionality I really needed. The learning curve was too steep for a person with only five hours a week. For several months I worked with a book called Lightweight Django. The title promised me much, but assumed Django and website development knowledge I did not have. Still, I stayed with the book for a long time. The chapter on using Django as a static website generator seemed especially relevant. However, that chapter's example was for a flat website, where everything was at the same level. There was no ability to put my code in a directory structure that matched the topical structure of the contents—where you could find, for instance, a page titled "Why Urubu?" in an Urubu section of a website called Close to the Machine.
Surely, Django could have met my needs, but I would have had to teach myself how, and the framework was so top-heavy that at my rate, it could have been years, if not decades, until I finally had my static HTML ported over.
Hyde, Pelican, etc.
I had heard of Hyde, knew it was Python-based, and played around with it a little. I liked the generator well enough, but thought maybe there were others I should explore first. I began an intensive search for a static website generator that would fit my needs. I came across a number of web pages on the topic, many comparing and contrasting different generators. Among the most informative were the following:
Python Generators
Full Stack Python
Libhunt Comparison
ArunRocks
I was discouraged by the claims that Hyde lacked a lot of documentation. I didn't want, and couldn't afford, to take a long time to familiarize myself with my development tools. Pelican seemed the best choice: popular, with a lot of developers collaborating on it, and having fairly readable blogs explaining how other people had redesigned their websites using it.
I was just about to jump in when I thought I'd spend one more session looking for alternatives. Just to be sure I was making the right decision.
Hello, Urubu
That's when I discovered Urubu. It started here:
Well, that's a little unusual—a blogger on software development who really knows how to write. But how had I missed this static website generator in my earlier research? It turns out that the first link in the section above—"Python Generators"—does include Urubu, but I probably hadn't explored it because I didn't think I was looking for a "micro CMS."
In his post, Jan Decaluwe says that Pelican is "blog-oriented," though not obviously so. This made me realize that I didn't want my website generator to impose its preconceptions of my content on me. Then Jan writes: "The project directory structure matches the website exactly." Which was precisely the problem I had when I tried to follow the Lightweight Django book described above.
The post above led me to the following:
By this time Jan had me on the line. All he had to do was reel me in. On the Concepts page of the manual, he writes:
I am a big fan of Steve Krug's book Don't Make Me Think, and I feel that the lessons from this book are still often ignored. Actually, the lack of focus of other tools on these ideas are the main reason why I wrote Urubu.
A main concept is good navigation.
I had never heard of this book, but I did appreciate a software developer who operated according to some guiding principles. Moreover, while Hyde supposedly had poor documentation, clearly with this manual Urubu offered documentation aplenty. When I came across the Urubu Quickstart Guide which Jan had thoughtfully provided his Urubu users, the deal was closed.