Markdown reports

Mkdocs

MkDocs is simple but powerfull static web site generator. Source files are written by default in Markdown, and configured with a single YAML configuration file. By using mkdocs-jupyter extension also Jupyter Notebooks can be included into web sites without modifications or intermediate file generation.

• mkdocs: https://mkdocs.org
• mkdocs material theme: https://github.com/facelessuser/mkdocs-material-extensions
• mkdocs jupyter extension: https://github.com/danielfrg/mkdocs-jupyter
• GitHub / Mastering Markdown: https://guides.github.com/features/mastering-markdown

Installation

Mkdocs and its extensions can be installed by using conda. Create a new conda environment or install required software one of the existing environment. Mkdocs is python based software so it should work nicely together with e.g. Jupyter Notebooks.

Create conda a new environment:

conda create -n mkdocs

Activate conda environment:

conda activate mkdocs

Install required packages:

conda install -c conda-forge mkdocs mkdocs-material mkdocs-jupyter

Project management

Initialize a new mkdocs project:

mkdocs new MyProject

Change directory to newly created project folder:

cd MyProject

Modify mkdocs.yml configuration file to customize web site layout, content and behavior. Example configuration file:

site_name: My Project  
site_author: Your name  
nav:  
    - Abstract: index.md  
    - Introduction: intro.md  
    - Methods: methods.md  
    - Results: results.ipynb  
    - Discussion: discussion.md  
theme:  
  name: material  
  palette:  
    primary: blue  
  features:  
    - toc.integrate  
    - header.autohide  
    - navigation.tracking  
repo_url: https://github.com/username/myproject  
edit_uri: docs/  
plugins:  
  - search  
  - mkdocs-jupyter  

Add content to the files. The files can be markdown (.md) documents or Jupyter Notebooks (.ipynb) documents.

Build your static web site. The generated files are placed into the site subdirectory:

mkdocs build

or

mkdocs build --clean

Inspect your web site locally by using your web browser at http://localhost:8000:

mkdocs serve

If you're using source code control (e.g. git) add a line containing site/ to your .gitignore file:

echo "site/" >> .gitignore

For example, listing of all the files (and whole content of the git repository) required to build this site looks like as follows:

    ├──.gitignore  
    ├──README.md  
    ├──mkdocs.yml  
    ├──docs  
    │  ├──index.md  
    │  ├──server_access_rights.md  
    │  ├──remote_access.md  
    │  ├──recommended_software.md  
    │  ├──working_on_servers.md  
    │  ├──markdown_reports.md  
    │  ├──resources.md  
    │  ├──images  
    │  │  ├──logo.png  
    │  │  ├──favicon.png  

The only mandatory files are mkdocs.yml configuration file and your markdown and/or Jupyter Notebooks in docs directory!

Deploying

The web site that you just built consists only of static files so you'll be able to host it from pretty much anywhere e.g. GitHub Pages. Only what you need to to do is to upload the contents of the entire site directory to wherever you're hosting your website from.