Skip to content

Mkdocs-et

1. Introduction

Do you know the static site generator Mkdocs, and the theme Material for Mkdocs ?

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

Mkdocs-et is a fully configurable bash script 1, whose purpose is to facilitate the use of Mkdocs and Material, and to add features such as:

  • install Mkdocs, Material and all folks 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.2.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.2.tgz
~/Downloads$ cd mkdocs-et-1.2
~/Downloads/mkdocs-et-1.2$

Run the script to see its usage: 2

$ ./mkdocs-et.sh 
---------------------------------------------------------------------------
  mkdocs-et.sh  V 1.2
  http://pageperso.lif.univ-mrs.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). 3

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.


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

  2. For ease of reading, we will now use the prompt $ instead of ~/Downloads/mkdocs-et-1.2$

  3. On Ubuntu, type sudo apt install virtualenv. The same holds on Windows 10 + WSL2 + Ubuntu. On MacOS, type brew install python3 virtualenv md5sha1sum