I recently used mkdocs again, the lovely documentation framework which comes with several useful plugins, nice styling and built-in PDF and static website generation. Sometimes it is a bit tricky to get everything installed on your machine to make in running, such as Python 3 and several add-ons, so you may want to run it inside a container.
Although there are several tutorials about setting up such an image with a dockerfile or a container with docker-compose, I had trouble to make it run. The main reason for that were 2 plugins I wanted to use in mkdocs:
I am not sure about print-site but with-pdf definitely won’t run because of dependencies not being fulfilled during the image built. I tried using Alpine and Ubuntu as base image - no luck.
Finally I got it running by disabling those plugins in mkdocs.yml so I didn’t have to install them in the container image. However, I am still using mkdocs Material design - which looks really slick.
This is the final result of my dockerfile:
FROM python:3-alpine3.14
ARG USER=1000
RUN adduser -h /usr/src/mkdocs -D -u $USER mkdocs \
&& apk add bash \
&& apk add git
ENV PATH="${PATH}:/usr/src/mkdocs/.local/bin"
USER mkdocs
RUN mkdir -p /usr/src/mkdocs/build
WORKDIR /usr/src/mkdocs/build
RUN pip install --upgrade pip
RUN pip install pymdown-extensions \
&& pip install mkdocs \
&& pip install mkdocs-material \
&& pip install mkdocs-rtd-dropdown \
&& pip install mkdocs-git-revision-date-plugin \
&& pip install mkdocs-git-revision-date-localized-plugin \
&& pip install mkdocs-blog-plugin \
&& pip3 install mkdocs-blogging-plugin \
&& pip3 install mkdocs-macros-plugin
# The following line is bcause of mkdocs build error: Unable to read git logs of
RUN git config --global --add safe.directory '*'
ENTRYPOINT ["/usr/src/mkdocs/.local/bin/mkdocs"]
LABEL mkdocs.image="3-alpine3.14"
To build the image just simply run this command in the folder where the dockerfile is:
docker build --tag 'mkdocs' --no-cache .
This will take about 2 minutes to build.
Assuming you are already inside your local folder of mkdocs (this is where the mkdocs.yml file is), you can then start the container with this command:
docker run --rm --name mkdocs -p 8100:8000 -v .:/usr/src/mkdocs/build mkdocs serve --dev-addr 0.0.0.0:8000
This looks more complicated than it actually is. This spins up a container and mounts your local folder to it. After you stop the container it is also being removed.
You can access the mkdocs with your browser using
http://0.0.0.0:8100
The container will monitor the “local” folder which is mounted to your actual work folder in the host file system. Every change you make here will reflect in reloading the page in your browser.
Notice the port that is used outside the container: I am using port 8100 here because I have Portainer running in my local Docker environment which already uses port 8000.
I hope this saves you some time - it took me a few hours to combine all the stuff I found online.