Mkdocs-et

1. Introduction

Mkdocs-et is a fully configurable bash script ¹, whose purpose is to facilitate the installation and use of Mkdocs and the theme Material for Mkdocs.

Mkdocs is a well-known static site generator, which allows to generate beautiful static sites from source files written in markdown format, with a Search box and responsive design, to write mathematical formulas like $\sqrt{x^2+1}$ in LaTeX syntax, and more.

Our script provides these features:

install or update Mkdocs, Material and all dependies;
put the installation at the user level in a python virtualenv, so that there will be no version conflicts with other python tools;
generate a site with a filtered subset of pages (main feature): this allows the elements of a course to appear progressively;
publish the resulting site with rsync on the target httpd server.

Moreover,

tables are sortable by default, but it's possible to set a table as not sortable, or even remove its header;
if you need to embed some PHP, .md files containing <?php will produce .php files, and it works out of the box, provided that PHP is enabled on your httpd server;
template language jinja2 is enabled and can be used in the .md file.

Mkdocs-et comes already pre-configured; configuration files and assets are stored in a small skeleton directory, which can be generated by the script.

2. Download

Ready to go? Download here the tarball : mkdocs-et-1.5.tgz

It contains the script mkdocs-et.sh and the source files of this entire site as a demonstration.

3. Tutorial

Unpack the tarball in a bash terminal:

$ cd ~/Downloads
~/Downloads$ tar xvfz mkdocs-et-1.5.tgz
~/Downloads$ cd mkdocs-et-1.5
~/Downloads/mkdocs-et-1.5$

Run the script to see its usage: ²

$ ./mkdocs-et.sh 
---------------------------------------------------------------------------
  mkdocs-et.sh  V 1.5
  https://pageperso.lis-lab.fr/~edouard.thiel/mkdocs-et/
---------------------------------------------------------------------------

USAGE:
    mkdocs-et.sh action
action:
    create-venv|remove-venv|update-venv|list-venv
    create-skel
    serve   [--all] [filters] [-p port] [--] [mkdocs options]
    publish [--all] [filters] [-f]      [--] [mkdocs options]

Warning: action expected

Ask the script to create a virtual environment and install the python modules (Mkdocs, Material and other plugins):

$ ./mkdocs-et.sh create-venv

The script will check if python3 and virtualenv are installed; if not, install them with your favourite package manager (Python version >= 3.6). ³

Once this is done, start the embedded web server:

$ ./mkdocs-et.sh serve --all

Now open your favourite browser on http://localhost:8000/ to see the result.

If the script fail by writing [Errno 98] Address already in use, try another port:

$ ./mkdocs-et.sh serve --all -p 8001

Note:

The embedded web server tracks all changes in the source .md files:
edit the source index.md of this page, write something and save the file; you will see mkdocs working in the terminal, then the page will be automatically updated in the browser.

Finally, see the page filtering in action: interrupt the script with Ctrl+c then rerun the script with

$ ./mkdocs-et.sh serve --lec 2 --prw 3

and reload the page in your browser: you will get the lecture pages from 1 to 2, and the practical work pages from 1 to 3.

The filter names and the number of filters are configurable in the script; we will see it later.

To publish the site on your httpd server, it will be as easy as typing ./mkdocs-et.sh publish --all or ./mkdocs-et.sh publish --lec 2 --prw 3, but before this, the target server address must be configured: see next section.

Bash version 4.3+. For Linux, and other Unix systems; it works also very well on Windows10 + WSL2. On MacOS, install recent bash by typing: brew install bash. ↩
For ease of reading, we will now use the prompt $ instead of ~/Downloads/mkdocs-et-1.5$. ↩
On Ubuntu, type sudo apt install virtualenv. The same holds on Windows 10 + WSL2 + Ubuntu. On MacOS, type brew install python3 virtualenv md5sha1sum. ↩