mkdocs wiki

Setting up a readthedocs wiki like 1,2,3!

Readthedocs has a beautiful and modern theme for wikis. They are mainly used for software wikis but could also be applied for anything else. To get one up and running yourself simply install mkdocs, build a sample page, modify it and host it somewhere.

Installation

You need Python installed, then simply install with pip:

1
pip install mkdocs

Change to a working directory and type the following command:

1
mkdocs new my-project

A basic sample page is generated. If you want the readthedocs theme (which you probably want) just change the following lines in mkdocs.yml:

1
2
3
4
5
site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

Afterwards modify the markdown files in docs folder. Build the static files and run a server when ready:

1
2
3
cd my-project
mkdocs build
mkdocs serve 

Done! On localhost:8000 you'll find your wiki.

mkdocs wiki

Deploy with Netlify

If you want to deploy it instantly and for free, just use netlify via drag'n'drop. Create an account, go to your sites and drag your site folder in the respective field.

netlify deploy

Your site is deployed in a second and assigned a quite random URL something.netlify.app.

netlify wiki deployed

Change the URL under site settings to yourprojectwiki.netlify.app and you're good to go! 🐃

If you want to know more about netlify and I set up geo.rocks see this blog post.