building the documentation


I changed from my homemade system to mkdocs, mainly due to the search facility. (I'm sure there are any number of other static site generators out there, but this one seemed to have the smallest footprint and was easiest to install and get going).

building the docs

what doesn't work in mkdocs

bad language guesses

It seems to be too hard to make it turn off its "guess the language" pseudo-smartness when you use a plain indented code block. And looking at the mailing list archives does not give me much hope this will be fixed. So you're left with strange colors on some random words in many code blocks!

(I could fence each of them with an explicit language but I'm reluctant to do that; plain markdown's plain indented code should be left plain, ideally!)

no hidden docs

Every document must appear in the document menu (top nav bar), even if it is several levels deep. The only way to have a document rendered without putting it on the nav bar is not to even list a page hierarchy, which makes them all come out in alphabetical order, which is useless for a project of this size.

The mailing list has some workarounds, but at the moment I am not using them. I'd already added all the documents willy-nilly anyway.

Except, ironically, this document; this will never be rendered -- you'll only see it in the source repo.

foo bar split across lines

If a foo bar is split across lines due to vim formatting, the bloody output also shows it split there. My constant OCD to reformat all paras has taken a hit, due to all these manually UN-formatted paragraphs.

TOC levels

The 'cinder' theme gives you 3 levels, but does not scroll the side nav at all (i.e., if you have too many entries, you just won't see the ones that were below the window bottom)! Sticking with default theme for now.

code highlight

  1. the "codehilite" extension seems too complicated looking at the steps described in https://pythonhosted.org/Markdown/extensions/code_hilite.html

  2. in any case they don't recognise gitolite syntax.

So we just use the

```LANG
...code...
```

syntax and let our preprocessor fix things up using vim. Kludgy, slow, annoying (all those xterms -- I need to implement caching for this), but it gets the job done with a minimum of fuss.

short anchors

can only be created like:

<h1 id="dl">download</h1>

Using

# <a id="dl" />download

causes some weird artefacts in the generated page.

At present I'm not using them at all; just using the long forms.