osourcese/mkdocs-materials repository overview

⁠Container

This container is meant as a development of markdown sites on your local network / computer, not for public access from the internet.

SSH and root access are enabled to make it easier to add new plugins for MkDocs and to access the machine with a development tool like Visual Studio Code where you can connect directly to a server and edit on place, or to build the finish site when its ready for export.

The exposed port must be higher than 1024 when run in so called rootless environment, the internal ports are 22/tcp and 8000/tcp.

⁠Persistent Data

Create a volume on this container that points to /home/mkadm/markdown in the container to store important site data in persistent storage.

⁠Security

The MkDocs server runs as a non root user inside the container to further lock down the container and works well with container systems running in rootless mode.

Default password for ssh user mkadm and root is mkadm, make sure to change these ASAP...

This needs to be done every time you update to a new version, and it will generate a new SSH token as well, looking into to possibility to keep this information between container versions.

Steps to update password:

podman exec -i -t -u 0 yourcontainer /bin/bash

or:

docker exec -i -t -u 0 yourcontainer /bin/bash

And then issue the following commands, you will be asked about new password, just enter the one you want to have.

passwd mkadm

and:

passwd root

And then you can just write exit to leave the container.

⁠GUI

The container web GUI contains more information about what is included, you can reach it on the designated port you assign to it when creating the container, same with SSH.

⁠Editing

You can either edit in place by SSH into the container or by uploading your files after editing, MkDocs spots changes directly and refresh itself to show the latest changes instantly and the base folder for files is /home/mkadm/markdown within the container.

⁠Create

This is the simplest create command you can use to test and get this container up and running, i recommend that you check out what more you can do around container creation, but this will get you started. Replace the following tags with your information, <name>, <volumename> and if you want to try a certain version change latest to the version number you want to run.

podman create --publish 8000:8000/tcp --publish 2222:22/tcp \
--name <name> --volume <volumename>:/home/mkadm/markdown \
docker.io/osourcese/mkdocs-materials:latest

Or:

docker create --publish 8000:8000/tcp --publish 2222:22/tcp \
--name <name> --volume <volumename>:/home/mkadm/markdown \
docker.io/osourcese/mkdocs-materials:latest

⁠Versions

The latest contains the latest versions of everything including themes and plugins at the time of build.

Naming for specific versions is our own versioning from building the container and each version is described below with the versions of MkDocs, Materials & Markdown, images older than 1 year will be removed to keep it clean and refreshed.

⁠latest:

MkDocs: 1.6.1 Materials: 9.7.6 Markdown: 3.10.2

⁠1.0.13:

MkDocs: 1.6.1 Materials: 9.7.6 Markdown: 3.10.2

⁠1.0.12:

MkDocs: 1.6.1 Materials: 9.7.1 Markdown: 3.10.0

⁠1.0.11:

MkDocs: 1.6.1 Materials: 9.6.20 Markdown: 3.9.0

⁠1.0.10:

MkDocs: 1.6.1 Materials: 9.6.15 Markdown: 3.8.2

⁠1.0.9:

MkDocs: 1.6.1 Materials: 9.6.14 Markdown: 3.7

⁠More...

Visit my site for more stuff⁠ or on Twitter/X⁠