setup mkdocs:
install dependencies
stuff to do on a debian 8 server:
-
install pip3:
apt install python3-pip
-
install mkdocs and extensions:
pip3 install mkdocs pymdown-extensions
-
optional for latex like math support:
pip3 install python-markdown-math
-
also optional: cleaner looking theme:
pip3 install mkdocs-material
-
setup git hooks
-
create a path where to build the site, e.g.:
/home/git/githookdata/testwiki/
-
create an bare git repo (e.g. with the web interface of your favorite git management software) in
/home/git/git-repositories/user/testwiki.git
-
clone the bare server side wiki repository manually for the first time:
git clone /home/git/git-repositories/user/testwiki.git
-
create a script to update the wiki and save it as
/home/git/githookdata/updateTestwiki.sh
:#!/usr/bin/env bash # i don't remember why, but unsetting $GIT_DIR is important unset GIT_DIR # change to dir where the master branch is checked out: cd /home/git/githookdata/testwiki/ # update repository copy git pull /home/git/git-repositories/user/testwiki.git/ master # build / update wiki. setting LC_ALL seems to be important, i also don't remember why LC_ALL=C.UTF-8 LANG=C.UTF-8 mkdocs build
-
create a git hook to run the update script after every push:
/home/git/git-repositories/user/testwiki.git/custom_hooks/post-receive
with content:#!/usr/bin/env bash /home/git/githookdata/updateTestwiki.sh
-
create a symlink to /var/www/:
ln -s /home/git/githookdata/testwiki/site /var/www/testwiki
wiki structure
now we have to fill the wiki repo with content. At first we need a config file called mkdocs.yml
like this:
site_name: Testwiki
theme: material
extra_javascript:
- https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML
markdown_extensions:
- mdx_math
- pymdownx.arithmatex
- pymdownx.emoji
- markdown.extensions.codehilite(linenums=true)
- pymdownx.magiclink
- toc(permalink=true)
- footnotes
the folder docs/
contains the wiki files in markdown syntax.