Welcome#

This project was generated with InitDocs, which aims to easily configure an MkDocs project based on the feature-rich Material for MkDocs template/extension. This allows you to focus on writing the markdown files, while the system takes care of rendering the documentation site.

Features#

• Preconfigured with a plethora of usable components using Material for MkDocs
• Reference implementations with code examples
• Search functionality
• Dark/light mode support
• Customizable color themes (mkdocs.yaml and _internal/stylesheets/extra.css)
• Provided single page render for printing documentation to pdf
• Easily managed using the initdocs cli

How to Write Pages#

General#

The documentation is rendered based on the markdown files found in the pages folder, located at the same level as the configuration file named mkdocs.yaml. To get started writing pages, it could be beneficial to take a look at the page for Referencere Implementations, which describes the plethora of components available, and code examples of how to utilize them. Finally, it is important that each markdown file starts with a h1 header (# <header>) for successful rendering.

Structure#

Due to the alphabetical ordering of documents, a recommended approach is to keep a numbered directory structure, e.g. sectionx.title, where x is the section number. This yield control over the rendered page order, while keeping the nature of loading all markdown files automatically, instead of manually defining each file.

If using a nested structure, one need to add a file .pages, with the following format:

title: <Title>
nav:
  - ... *.md

Just add a title, and all of the files in the directory will be rendered as a section. You may nest as many levels down as you want, as long as there exists a .pages file importing all the written markdown files. Finally, the title defined in this file will only be used if multiple markdown files exists in the section, else the h1 header of the single file will be used instead.

In the .pages file, one is free to define each markdown page to include in a given order, instead of importing all markdown files located at the same level.

How to Build and Serve#

(Recommended) Docker Approach#

Ensure You Have Docker Installed#

Verify that you have Docker installed:

docker --version

If not installed, please head over to this blog post to get acquainted with Docker.

Please also ensure that Docker is running.

Docker Compose Services#

The process of building and serving this documentation has been made quite simple with the use of docker compose, defining dedicated services for building and serving your documentation.

Building#

If you want to build the project into static files, you can utilize the service docs-build. Before running the command, you should ensure that your working directory is set to the documentation project being where you find docker-compose.yaml, mkdocs.yml and the pages folder. To verify, print ls in your terminal and these should be among the listed items. To build, we can run an ephemeral container which builds a static site as follows:

docker compose run --rm docs-build

This command will:

• If not run before, build the Docker Image from the instructions in the dockerfile
• Run an ephemeral container which builds your documentation and place the static site in a directory named site.

When built, the index.html file inside this directory can be served, for example through a reverse proxy like nginx, or a Live Server/Live Preview extension in Visual Studio Code.

Serving#

It is also possible to serve the project with a hot-reloading server. This means that on every change in the mkdocs.yaml file or pages folder, the docs will reload. To serve, run one of the two commands below. The -d flag stands for detached mode, which means that it will run in the background without printing terminal output. If you want to see the terminal output, simply skip the flag.

# Serve in detached mode
docker compose up docs-serve -d

# Serve with terminal output
docker compose up docs-serve

Local Python Approach#

Python and PiP#

First, ensure you have Python and PiP installed. This can be checked by the commands python --version and pip --version. If not installed, it is recommendended to install both through Pyenv (blog post), but MkDocs also has a guide on installation.

(Optional) Virtual Environment#

It is recommended to use a virtual environment for installing the required Python packages. This can be setup with the command python -m venv .venv, and sourced (activated) with source .venv/bin/activate. If ran on Windows, although one should consider using WSL or Linux, the created directory will be named /Scripts instead of /bin. To deactivate, simply run deactivate in your terminal. Once sourced, all requirements will be installed to your virtual environment.

Install Requirements#

To install the requirements, run

pip install -r requirements.txt

We should now be able to build or run the documentation server!

Commands#

Serve#

Start the live-reloading docs server, accessible at localhost:8000 or 127.0.0.1:8000.

python -m mkdocs serve

Build Static Site#

Build a static documentation site, where the files are generated in a new directory named site.

python -m mkdocs build

Print Help#

Print help message and exit.

python -m mkdocs --help

Generate PDF#

If you want to generate a pdf file of the documentation, a single page render of the entire documentation project is made available at path /print_page.html. Either, you can navigate to this path and export/print yourself, or use the provided shell script for (1) building a static site and (2) generate the pdf using Docker.

For the latter, simply run the following command, given that Docker is installed:

bash generate_pdf.sh

Project Layout#

pages/
    _internal/         # Internal files
    assets/            # Media such as images, SVGs, etc.
    index.md           # The documentation homepage
    **/[...].md        # Other markdown pages
site/
    index.html         # Index page of static website
    ...                # All files in built docs
mkdocs.yml             # The configuration file
readme.md              # Information on setup
requirements.txt       # Pip requirements
dockerfile             # Docker image instructions
docker-compose.yaml    # Docker Compose Services
generate_pdf.sh        # Script to generate pdf