Skip to content

2. Configuration

2.1. The skeleton directory

The whole configuration lies in the sub-directory skel-mkdocs-et/. Here is its organization:

$ tree --dirsfirst skel-mkdocs-et/
skel-mkdocs-et/
├── images
│   └── tux2.gif
├── includes
│   ├── example1.md
│   ├── example2.txt
│   ├── mydefs.html
│   └── scores.php
├── javascripts
│   └── config.js
├── overrides
│   └── main.html
├── stylesheets
│   └── extra.css
├── conf-mkdocs-et.sh
├── htaccess
└── mkdocs.yml

The sub-directories will be copied as is in the site:

  • images/ : put here for instance your favicon.ico, and every image your site needs.
  • includes/ : some files to be included in the pages, here examples.
  • javascripts/ : the file config.js is executed on each page loading.
  • overrides/ : it contains theme customizations.
  • stylesheets/ : the file extra.css is included in each page.

The three last files play the following role:

  • conf-mkdocs-et.sh : the main config file for Mkdocs-et, see below.
  • htaccess : it will be copied as .htaccess to the root of the site. It indicates to the httpd (Apache) server how to handle some mime types and file extensions.
  • mkdocs.yml : the main config file for Mkdocs, see right after.

Note:

When in serve mode (mkdocs-et.sh serve running), each time a file is modified in these subdirectories, Mkdocs will immediatly re-build everything and update the page seen on http://localhost:8000/, in the same way as for the .md files in the main directory.

The configuration files conf-mkdocs-et.sh and mkdocs.yml in turn are monitored by mkdocs-et.sh each 10 seconds, so it may take a little longer for the automatic update to fire.

2.2 The file conf-mkdocs-et.sh

The file skel-mkdocs-et/conf-mkdocs-et.sh is the main configuration file for Mkdocs-et; it will be sourced by the bash script mkdocs-et.sh at each run.

Target web server

The file is self-documented. The first part describe your target web server:

# Your login on the target web server
TARGET_HOST="mylogin@myserver.fr"

# Base directory on the target server
TARGET_DIR="~/public_html/mysite"
ssh connection

The script run more smoothly if it can connect via ssh without a password; for that, create a public key and copy it to the target server (replace the target host below):

$ test -f ~/.ssh/id_rsa.pub || ssh-keygen -t rsa
$ ssh-copy-id -i ~/.ssh/id_rsa.pub mylogin@myserver.fr

Now that it is done, you can publish your web site simply by typing

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

or by filtering out

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

When in filtering mode, the pages hidden by the filters will be removed from the server (thanks to the rsync option --delete).

Note:

The script first display the changes that will be made (rsync --dry-run), then ask you to continue. To force the mirroring, add option -f at the end of the command line.

The second part describe the Navigation menu (left or top menu on the page). It will be used by mkdocs-et.sh to generate on the fly the nav: section for the YAML configuration file mkdocs.yml.

This is related to the main feature of Mkdocs-et, which is filtering pages to be published.

The definitions come in three parts: the first (NAV_BEGIN) and the third (NAV_END) will always be included, whereas the second (NAV_FILTERS + NAV_FILES) is the filtered part.

# Navigation : mandatory part
# Line format is "|file_name|short_title", 
# where the first char is the separator (here "|").
NAV_BEGIN=(
    "|index.md|Main page"
    "|config.md|Configuration"
    "|new-site.md|Creating a new site"
)

NAV_END=(
    "|todo.md|Todo"
    "|about.md|About"
    "|http://www.myserver.fr/~mylogin/index.html|Back"
)

# Filters for navigation :
# - line format is "option:file_pattern"
# - each option will be available as a command line argument "--option"
# - each file corresponding to file_pattern will be copied on the site
#   (? stands for 1 char and * stands for any string)
# - the number in the file name can be in any position, but not in an extension
NAV_FILTERS=(
    'lec:lec-??-*.md'
    'prw:prw-??-*.md'
)

# List of titles associated to filtered files.
# Line format is "|file_name|short_title"
# where the first char is the separator (here "|").
NAV_TITLES=(
    "|lec-01-basic.md|L 01 - Markdown syntax"
    "|lec-02-more.md|L 02 - More Markdown"
    "|lec-03-extend.md|L 03 - Extended Markdown"
    "|lec-04-other.md|L 04 - Other extensions"
    "|prw-01-maths.md|PW 01 - Maths"
    "|prw-02-diag.md|PW 02 - Diagrams"
    "|prw-03-php.md|PW 03 - Php form"
    "|prw-04-jinja.md|PW 04 - Jinja2"
)

Beware, the syntax VARIABLE=(...) is bash syntax for a list, in which there must be no space around = and no comma inside parenthesis.

2.3 The file mkdocs.yml

The file skel-mkdocs-et/mkdocs.yml is the Mkdocs configuration file, in YAML format. Beware to the indentation and to the - and : signs!

The file is already configured, but feel free to modify it, using the documents:

The nav: section defines the navigation menu. It must be at the end of the file because mkdocs-et.sh will append sections on the fly, depending on filter options. If the nav: line is commented, the script will append one.

As you can see, a number of plugins and extensions are selected; other ones may be added, but some of them can conflict with each other or not run at all.