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

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