I have for years used OneNote for keeping to-do lists and some general notes. Recently though I got particularly annoyed by it’s poor syncing between devices and collaborators.

For quick to-do lists I have moved to Keep which has been working very well for this basic task.

This left choosing a more long term place to store the longer form notes and knowledge I had in OneNote. A self-hosted approach appealed to me for a number of reasons.

Coincidentally a recent episode of selhosted.show took on the topic of Which Wiki Wins.

They looked at:

I also took a look at https://www.gitbook.com/

In the end I chose MkDocs. I like markdown and not having to run a database as it generates static HTML as output.

Getting started is very quick:

pip install --upgrade pip
pip install mkdocs
mkdocs new wiki
cd wiki
mkdocs serve

To improve the look and feel I moved to a material theme.

pip install mkdocs-material

And then in the mkdocs.yml added:

theme:
  name: 'material'

Porting from OneNote

I use Visual Studio Code as my editor mostly. To help editing markdown I use some plugins:

  • markdownlint - Adds linting to ensure I keep my markdown correct.
  • Markdown Shortcuts - Mainly useful for Ctrl M + B to create lists and Ctrl + L to wrap bare links.
  • Spell Right - I make a lot of spelling mistakes.

To migrate tables I copied and pasted in to Excel and then in to an online tool to convert to markdown.

OneNote likes to end each line with a space which does not agree with the markdown linter. To get around this I used find replace in Notepad++ to remove occurrences of “ $”.