build: create MkDocs OCI image from scratch (#246)

Author: Djaytan

docs/user-guide/Dockerfile

@@ -0,0 +1,23 @@
+# syntax=docker/dockerfile:1.16.0@sha256:e2dd261f92e4b763d789984f6eab84be66ab4f5f08052316d8eb8f173593acf7
+# check=error=true
+
+# Note: impossible to rely on v3.13.14 (missing 'cache_clear' function error)
+FROM docker.io/python:3.12.11-alpine@sha256:c610e4a94a0e8b888b4b225bfc0e6b59dee607b1e61fb63ff3926083ff617216
+
+WORKDIR /run
+
+# Install MkDocs
+RUN pip install mkdocs-material[recommended]
+
+# Install MkDocs Git-related features (e.g. revisions, collaborators, ...)
+RUN apk add --no-cache git && \
+    pip install \
+      mkdocs-git-revision-date-localized-plugin \
+      mkdocs-git-committers-plugin-2 && \
+    git config --system --add safe.directory /run
+
+USER daemon
+
+EXPOSE 8000
+
+ENTRYPOINT ["mkdocs"]

docs/user-guide/README.md

@@ -36,14 +36,24 @@ Instead, open the site using one of the following URLs:
 * `http://localhost:8000/docker-papermc-server/`
 * `http://127.0.0.1:8000/docker-papermc-server/`
 
+## 🛠 Wrapper Script
+
+To run `mkdocs` commands manually, use the `mkdocs.sh` wrapper script. For example:
+
+```bash
+./mkdocs.sh build
+```
+
+That said, unless you have a specific reason, it’s recommended to use `localdev.sh`, as it handles everything needed for local development.
+
 ## ➕ Adding Dependencies
 
 When introducing new dependencies, make sure to update both the **local development environment** and the **CI build environment**, as they are managed
 separately.
 
 ### 💻 Locally
 
-To update the local environment, open the `wrappers/mkdocs/Dockerfile` and modify the `RUN pip install ...` line to include any additional packages you need.
+To update the local environment, open the `Dockerfile` and modify the `RUN pip install ...` line to include any additional packages you need.
 
 ### 🤖 In CI
 

docs/user-guide/localdev.sh

@@ -5,5 +5,6 @@ set -eu
 SCRIPT_DIR=$(cd "$(dirname "$0")" > /dev/null 2>&1 && pwd -P)
 
 echo 'The preview is going to be available at http://localhost:8000/docker-papermc-server/'
+echo
 
-sh "${SCRIPT_DIR}"/wrappers/mkdocs/mkdocs
+sh "${SCRIPT_DIR}/mkdocs" serve --dev-addr '0.0.0.0:8000'

docs/user-guide/wrappers/mkdocs/mkdocs docs/user-guide/mkdocs.shdocs/user-guide/wrappers/mkdocs/mkdocs renamed to docs/user-guide/mkdocs.sh

@@ -3,7 +3,7 @@
 
 set -eu
 
-SCRIPT_DIR=$(cd "$(dirname "$0")" > /dev/null 2>&1 && pwd -P)
+SCRIPT_DIR="$(cd "$(dirname "$0")" > /dev/null 2>&1 && pwd -P)"
 
 # On Windows environments (Cygwin, MinGW, MSYS), Docker volume mounts require Windows-style paths.
 # However, automatic path conversion by MSYS can cause unexpected issues,
@@ -20,13 +20,16 @@ case "$(uname)" in
     ;;
 esac
 
-ROOT_PROJECT_DIR="${SCRIPT_DIR}/../../../.."
+ROOT_PROJECT_DIR="${SCRIPT_DIR}/../.."
 
-docker build -t docker-papermc-server/mkdocs "${SCRIPT_DIR}"
+echo 'Building Docker image for MkDocs (can take a while)'
+docker build --progress quiet -t docker-papermc-server/mkdocs "${SCRIPT_DIR}"
 
+echo
+echo 'Running MkDocs:'
 docker run --rm -p 8000:8000 --name docker-papermc-server-mkdocs \
-  --volume="${ROOT_PROJECT_DIR}:/docs" \
-  --workdir /docs/docs/user-guide \
+  --volume="${ROOT_PROJECT_DIR}:/run" \
+  --workdir /run/docs/user-guide \
   -e MKDOCS_GIT_COMMITTERS_APIKEY="$(gh auth token)" \
   docker-papermc-server/mkdocs \
   "$@"