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