mkdocs basic authentication

An static site generador like mkdocs is great for writing documentation. Sometimes the information is not secret but we don't want it available to general public. Here's a workaround for such scenarios.

This solution adds basic authentication the pages generated by mkdocs. It renames static html files as php files and adds php code which provides the basic authentication functionality.

tl;dr

• setup credentials in the mkdocs.yml file.
• add php code to base.html template file (if other than the readthedocs theme).
• write some docs.
• run make full and check the results.

configuration

Mkdocs allows for customizing the current theme by using the custom_dir variable in the mkdocs.yml configuration file.

The theme.custom_dir configuration value is used in combination with an existing theme, the theme.custom_dir can be used to replace only specific parts of a built-in theme.

From the docs.

theme: 
  name: readthedocs
  custom_dir: 'theme_addons/'

The user/password credentials are also defined in the mkdocs.yml file.

extra:
  username: "admin"
  password: "secret"

usage

git clone [email protected]:otsuarez/mkdocs_auth.git
cd mkdocs_auth
pip install -r requirements.txt
make full

using virtualenv

# install virtualenv
git clone [email protected]:otsuarez/mkdocs_auth.git
cd mkdocs_auth
virtualenv --python=/usr/bin/python2.7 .pyenv
source .pyenv/bin/activate
pip install -r requirements.txt
make full

Open in your browser http://localhost:8080/.

using a container

docker run -p 8080:8080 --rm -it ubuntu:bionic bin/bash
apt update -y
apt install -y git  build-essential python-pip php
cd root
git clone https://github.com/otsuarez/mkdocs_auth.git
cd mkdocs_auth
pip install -r requirements.txt
make full

other themes

The readthedocs theme is being used, for another theme, make sure to have the right base.html template file with the php code added.

cp $(theme="$(egrep "^theme" mkdocs.yml| cut -f2 -d:)" ; locate base.html | grep $theme) theme_addons/

If using a virtualenv:

cp $(theme="$(egrep "^theme" mkdocs.yml| cut -f2 -d:)" ; find .pyenv -name  base.html  | grep $theme) theme_addons/

Then add the php code to the base.html file.

tmp="$(mktemp)" && cat theme_addons/basic_auth.inc theme_addons/base.html >"$tmp" && mv "$tmp" theme_addons/base.html 

Check the Makefile file for reference on the actual commands and scripts being executed.