Local installation
In order to preview MkDocs as you write, you will first need to run MkDocs locally with Docker.
Warning
The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.
Install with docker¶
This repository publishes an image that already includes the plugins used by the site. After a production tag, and after the GHCR package is set to Public, pull without logging in:
The mkdocs executable is the entrypoint and serve is the default command. See the container README for the full tag policy. While the image is in the 0.x series, there is no moving v0 tag.
The image includes:
- mkdocs-material
- mkdocs-awesome-nav
- mkdocs-macros-plugin
- mkdocs-git-revision-date-localized-plugin
- mkdocs-git-committers-plugin-2
Warning
The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.
Verify required plugins¶
The published image is pinned in container/requirements.txt. Site deploy in .github/workflows/publish-pages.yml still installs packages with pip and does not use this image.
Add plugins to the image¶
If you need extra plugins beyond what this repository publishes, extend the public image:
# https://squidfunk.github.io/mkdocs-material/getting-started/#with-docker
FROM ghcr.io/rwaight/rwaight.github.io/mkdocs-material
# be sure to include the plugins that are installed in the 'publish-pages' workflow
# check the '.github/workflows/publish-pages.yml' file
# Plugins used by this site are already in the published image (container/requirements.txt).
# Site deploy in .github/workflows/publish-pages.yml still pip-installs and does not use this image.
RUN pip install mkdocs-glightbox