Confluence is a great tool, but it has some important drawbacks:

• It is hard to control how the site gets indexed by search engines

• It is paid, so the content disappears if I happen to die

The second small issue could be solved if I could put the site on Github, for instance. But then I need something that can easily create a website without a shitload of work, and without having to write (x)html. This clearly needs something where the content is separate from the stuff that gives the site its look and behavior.. And we need something in which to author the site that does not suck the Big Hairy Balls.

Portable text format

To prevent having to write HTML I would like to use Markdown. This is a very simple format with more than enough things to write simple articles. Markdown is very portable, so the written words will not get lost if I change platforms.

You can of course write markdown just like that, in any editor. But this makes a few things really, really hard:

• I use a lot of images. These usually come from the Clipboard. It is not fun to have to save all of those by hand somewhere and then type the magic invocation that shows the image..

• Documents contain links to other documents. These links rot when you work on a site. We need something that:

  • Checks that links are still valid

  • Renames links when files are renamed

I checked a large amount of so called handy Markdown editors but most of them just focus on being able to edit text as “wysiwyg”. This is utterly useless, of course; preview is more than enough. Most editors cannot do either images nor link checks. The few that could do images did it clumsily, and I found none that properly handles link checks.

I also checked IntelliJ Idea which has several Markdown related plugins. They also have a product called “Writerside”. But neither of these did even the basics properly - pretty amazing.

Then I found out that VS Code, the free editor from Microsoft, actually has very good Markdown support! It does all I need, and it Just Works - a first for Microsoft, for me. So that settles the writing part comfortably; I should not miss Confluence for that.

Static site generators

The second part is to pick a static site generator. That should be easy, they are popular and there are a lot of them. How naive. I tried a few of them, and then I gave up….

Common complaints about static site generators

These generators come in all kinds and shapes. There are some that are whole ecosystems of things that you can do to some site; they are development tools, not site generation tools.

All the generators I played with had shit documentation. Not in the basics; they all explain how to get them installed, and many of them have easy setup tools that lets you “generate” a site with a few keystrokes, often even with the publishing code generated as well.

What they suck at is describing properly how you should place your content, and many have absolutely idiotic rules. There are no good examples of how to do simple things, and simple things often do not work.

Another big issue is error messages. A lot of these things report errors in an absolutely terrible way - if at all. The worst offender was Hugo in which it appears to be impossible to make an error, despite the fact that I spent half a day to bloody get it to output something.

Many generators also report errors just as compile errors because part of their config is just raw Python, Go, Javascript or whatnot. That is horrible. Use a proper format, and report proper context related errors for God’s sake!

Another bad thing is that all of these things want to focus on blogging. That is fine, but I do not WANT to blog, I just want to produce static pages for my content - and with a home page that is my content too. While all of the things I tested can do static pages they all seem more an afterthought.

Hugo

Hugo is a dripping pile of manure. No other words for it.

• The documentation sucks

• The idiot thing just runs, yeah, very fast, but gives no errors whatshowever

• Finding WHY things do not work is an exercise in frustration.

I also noticed that something that I barely got to work a bit a month before stopped working after some updates, with this time really interesting error messages. Unstable crap.

Pelican

Pelican was the one I got to work the quickest. I could relatively quickly get the first page to show. Getting themes to work was harder because for the life of me I have no idea where the theme actually comes from. You can install a theme with the pelican-theme tool (which is nice) once you downloaded it from wherever, but it’s a mystery to me where that theme goes once installed.

The tool gave quite a lot of stupid errors. For instance if your markdown has no Title: in the frontmatter then you get a lot of errors for pages; these are not clear in that that tag is missing from a page.

The deal breaker for Pelican came when I started to use the pages. My home page contains links to the other documents, in Markdown format. I.e. a link would be:

These refer to documents in the source tree. But to my dismay these were not translated to the proper html links: they remained as they were, so clicking them caused a browser 404. I then found out this pearl of idiocy:

Open

You need to write your links in a completely idiotic way to get them to work → bye bye portability.

There also was an issue with images. I keep my documents in a folder per document, and add the images there too so that things can be easily found and maintained. This of course does not work.

Exit Pelican.