Skip to content

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/

    #!/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
  • 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


    - 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.