ddidier/mkdocs repository overview

⁠NDD Docker MkDocs

1. Introduction⁠
2. Installation⁠
   1. From source⁠
   2. From Docker Hub⁠
3. Usage⁠
   1. Initialization⁠
   2. Non-interactive mode⁠
      1. Helper scripts⁠
      2. Docker commands⁠
   3. Interactive mode⁠
4. Configuration⁠
   1. Add new extensions⁠
5. Development⁠
   1. Coding⁠
   2. Releasing⁠

⁠Introduction

The Material for MkDocs⁠ generator with extensions, plugins and custom utilities.

The versioning scheme of this Docker image is <MATERIAL_FOR_MKDOCS_VERSION>-<DOCKER_IMAGE_VERSION>. For example, 9.7.3-1 stands for the first version of this Docker image using Material for MkDocs⁠ 9.7.3.

There are two published images:

• ddidier/mkdocs:<VERSION> for HTML builds only.
• ddidier/mkdocs:<VERSION>-pdf which adds PDF support (WeasyPrint⁠ + mkdocs-to-pdf).

Besides the Material for MkDocs⁠ generator, this image contains and is configured for the following extensions:

• mkdocs-awesome-nav-plugin⁠
• mkdocs-build-plantuml-plugin⁠
• mkdocs-enumerate-headings-plugin⁠
• mkdocs-git-revision-date-localized-plugin⁠
• mkdocs-macros-plugin⁠
• mkdocs-print-site-plugin⁠
• mkdocs_puml⁠
• mkdocs-static-i18n⁠
• mkdocs-table-reader-plugin⁠
• mkdocs-to-pdf⁠ (only in ddidier/mkdocs:<VERSION>-pdf)

This image also contains some utility scripts to make your life easier.

References:

• ddidier/mkdocs image on Docker Hub⁠
• ddidier/mkdocs sources on GitLab⁠

The image is based on the official Material for MkDocs image⁠.

⁠Installation

⁠From source

The sources are available on GitLab⁠.

git clone [email protected]:ddidier/docker-mkdocs.git
cd docker-mkdocs
make

⁠From Docker Hub

The Docker image is available on Docker Hub⁠

export NDD_MKDOCS_VERSION="9.7.3-2"
docker pull ddidier/mkdocs:"${NDD_MKDOCS_VERSION}"
# or if you need advanced PDF printing:
docker pull ddidier/mkdocs:"${NDD_MKDOCS_VERSION}-pdf"

⁠Usage

The documentation directory on the host is called ${HOST_DATA_DIR} in the remainder of this document.

The directory ${HOST_DATA_DIR} on the host must be mounted as a volume under /data in the container. Use -v "${HOST_DATA_DIR}":/data to use a specific documentation directory. Use -v "${PWD}":/data to use the current directory as the documentation directory.

MkDocs⁠ is executed inside the container by a custom user who is created by the custom Docker entry point. You must pass to the container the environment variable HOST_USER_ID set to the UID of the user the files will belong to. This is the -e HOST_USER_ID="${UID}" part in the examples of this documentation.

ℹ️ Helper scripts are provided which already take care of this plumbing.

⁠Initialization

MkDocs⁠ provides the new command to create the skeleton of a project, but don't use it! Use mkdocs-new instead!

⚠️ The directory ${HOST_DATA_DIR} must already exist, otherwise the script will fail!

docker container run -it --rm   \
    -v "${HOST_DATA_DIR}:/data" \
    -e "HOST_USER_ID=${UID}"    \
    -e "DEBUG=true"             \
    "ddidier/mkdocs:${NDD_MKDOCS_VERSION}" \
        mkdocs-new

You should now customize the content of bin/variables.sh, mostly the project name and the exposed port.

⁠Non-interactive mode

The so-called non-interactive mode is when you issue commands directly from the host.

⁠Helper scripts

ℹ️ Helper scripts are provided to help you with common tasks and are the recommended way to go.

They are located in the bin directory of the generated project. They are configured with default variables located in the bin/variables.sh file. Each one of them can be called with --help to display all the available options.

To generate the HTML documentation, call:

./bin/build-html.sh

To generate the HTML documentation, and watch for changes with live reload, call:

# use the default port (i.e. 8000)
./bin/serve-html.sh

# use a custom port (e.g. 12345) so you can have multiple builds at the same time
./bin/serve-html.sh --port 12345

# use --help to see all the available options
./bin/serve-html.sh --help

To generate the HTML and the PDF documentations, call:

./bin/build-pdf.sh

ℹ️ And to make your life even a little easier, a Makefile is also generated at the root of your project.

Usage is really simple at the expanse of not being customizable:

• to generate the HTML documentation, just call make build-html
• to generate the HTML and the PDF documentations, just call make build-pdf
• to generate and serve the HTML documentation, just call make serve-html
• to package the documentation, just call make package

⁠Docker commands

You can of course directly use the MkDocs⁠ commands without relying on the helper scripts.

To generate the HTML documentation, call mkdocs build:

docker run -it --rm -v "${HOST_DATA_DIR}":/data -e HOST_USER_ID="${UID}" ddidier/mkdocs:"${NDD_MKDOCS_VERSION}" mkdocs build

To generate the HTML documentation, and watch for changes with live reload, call mkdocs serve:

# use the default port (i.e. 8000)
docker run -it --rm -v "${HOST_DATA_DIR}":/data -p 8000:8000 -e HOST_USER_ID="${UID}" ddidier/mkdocs:"${NDD_MKDOCS_VERSION}" mkdocs serve
#                                                  ^^^^
#                                                  open your browser at http://localhost:8000/

# use a custom port (e.g. 12345) so you can have multiple builds at the same time
docker run -it --rm -v "${HOST_DATA_DIR}":/data -p 12345:12345 -e HOST_USER_ID="${UID}" ddidier/mkdocs:"${NDD_MKDOCS_VERSION}" mkdocs serve --dev-addr "0.0.0.0:12345"
#                                                  ^^^^^                                                                                                        ^^^^^
#                                                  open your browser at http://localhost:12345/                                                 customize server port

To generate the HTML and the PDF documentations, call mkdocs build (use the -pdf image):

docker run -it --rm -v "${HOST_DATA_DIR}":/data -e HOST_USER_ID="${UID}" -e NDD_MKDOCS_BUILD_PDF=true ddidier/mkdocs:"${NDD_MKDOCS_VERSION}-pdf" mkdocs build
#                                                                           ^^^^^^^^^^^^^^^^^^^^^^^^^                                      ^^^^

⁠Interactive mode

The so-called interactive mode is when you issue commands from inside the container.

docker container run -it --rm   \
    -v "${HOST_DATA_DIR}:/data" \
    -e "HOST_USER_ID=${UID}"    \
    -e "DEBUG=true"             \
    "ddidier/mkdocs:${NDD_MKDOCS_VERSION}"

You should now be in the /data directory, otherwise just cd to /data.

You can now use MkDocs⁠ in the original way:

• to generate the HTML documentation, call mkdocs build
• to generate the HTML and the PDF documentations, call NDD_MKDOCS_BUILD_PDF=true mkdocs build (use the -pdf image)
• to generate and serve the HTML documentation, call mkdocs serve

⁠Configuration

⁠Add new extensions

If you want to use an extension which is not already bundled with this image, you need to:

1. create a new Dockerfile extending the ddidier/mkdocs image
2. install the Python package(s) of the extension(s) inside the Dockerfile
3. reference the extension(s) in the mkdocs.yml configuration file

#
# Dockerfile
#
FROM ddidier/mkdocs:<VERSION>

RUN pip install 'a-mkdocs-extension       == A.B.C' \
                'another-mkdocs-extension == X.Y.Z'

⁠Development

⁠Coding

The Makefile provide some useful targets:

• make clean to clean temporary artifacts
• make build to build the Docker image
• make test to run the tests
• make test-quality to run the quality checks ([ShellCheck])
• make all is a shortcut to make clean build test test-quality

⚠️ Do not forget to rebuild the Docker image before testing!

⁠Releasing

Docker Hub doesn't provide an API to update the README anymore: when a release has been created, don't forget to manually update the README on Docker Hub.