Mkdocs Material

When I first started the project, I used GitHub Wiki for docs. It worked, but... meh. In particular, combining site and page navigation into 1 tree on the right obscured the organization of the docs... and product. That's a serious problem.

I was delighted to discover GitHub Docs where you can build a minimal web site of static pages.

But what really made it work was the addition of mkdocs-material, which is now the basis for the current docs. It enabled me to define navigation (the left tree), and automitically creates the table of contents on the right. I think you'll agree the transformation was magical.

It was not to hard to set up, since my pages were all markdown. Hightlights, to perhaps save you some time:

  1. Create a docs folder

    • If you have wiki docs, you can get all the pages using the link in the lower right

  2. Create a mkdocs.yml (navigation, etc)

  3. Create a GitHub Workflow so that when you commit doc changes, the doc site is rebuilt.

There was 1 confusion, which was nearly funny. I read the gh-pages docs to say that I should put my pages in that branch. Uh-uh. That's the branch used to build the html output; when it built, it overwrote my source pages. Not a big problem, but a surprise you probably want to avoid.