docs: integrate Git in user guide (view/edit buttons and revisions) (#241)

Author: Djaytan

.github/workflows/docs-deploy.yml

@@ -38,6 +38,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
+          fetch-depth: 0 # Required by MkDocs' revisioning feature
 
       - name: Setup Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0

.github/workflows/docs-validate.yml

@@ -38,6 +38,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
+          fetch-depth: 0 # Required by MkDocs' revisioning feature
 
       - name: Setup Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0

docs/user-guide/.gitignore

@@ -0,0 +1 @@
+.cache/

docs/user-guide/Dockerfile

@@ -0,0 +1,8 @@
+# syntax=docker/dockerfile:1.16.0@sha256:e2dd261f92e4b763d789984f6eab84be66ab4f5f08052316d8eb8f173593acf7
+# check=error=true
+
+FROM docker.io/squidfunk/mkdocs-material:9.6.14@sha256:eb04b60c566a8862be6b553157c16a92fbbfc45d71b7e4e8593526aecca63f52
+
+# Add revisioning feature: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#revisioning
+RUN apk add --no-cache git && \
+    pip install mkdocs-git-revision-date-localized-plugin

docs/user-guide/mkdocs.sh

@@ -14,8 +14,10 @@ if [[ "$(uname)" =~ (CYGWIN.*)|(MINGW.*)|(MSYS.*) ]]; then
   SCRIPT_DIR="$(cygpath --windows "${SCRIPT_DIR}")"
 fi
 
+ROOT_PROJECT_DIR="${SCRIPT_DIR}/../.."
+
+docker build -t squidfunk/mkdocs-material "${SCRIPT_DIR}"
+
 echo 'The preview is going to be available at http://localhost:8000/docker-papermc-server/'
 
-docker run --rm -it -p 8000:8000 --volume="${SCRIPT_DIR}:/docs" \
-  squidfunk/mkdocs-material:9.6.14@sha256:eb04b60c566a8862be6b553157c16a92fbbfc45d71b7e4e8593526aecca63f52 \
-  "$@"
+docker run --rm -it -p 8000:8000 --volume="${ROOT_PROJECT_DIR}:/docs" --workdir /docs/docs/user-guide --name mkdocs squidfunk/mkdocs-material "$@"

docs/user-guide/mkdocs.yml

@@ -9,18 +9,29 @@ copyright: >
 
 docs_dir: src/
 
+repo_name: Djaytan/docker-papermc-server
+repo_url: https://github.com/Djaytan/docker-papermc-server
+edit_uri: edit/main/docs/user-guide/src/
+
 theme:
   name: material
   favicon: assets/logo.png
   logo: assets/logo-flat.png
 
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
+
   features:
     - navigation.instant
     - navigation.instant.progress
     - navigation.sections
     - navigation.top
     - search.suggest
     - search.highlight
+    - content.action.view
+    - content.action.edit
 
   palette:
     # Palette toggle for automatic mode
@@ -56,6 +67,8 @@ nav:
 
 plugins:
   - search
+  - git-revision-date-localized:
+      enable_creation_date: true
 
 markdown_extensions:
   - admonition

docs/user-guide/requirements.in

@@ -1 +1,2 @@
 mkdocs-material
+mkdocs-git-revision-date-localized-plugin

docs/user-guide/requirements.txt

@@ -7,7 +7,9 @@
 babel==2.17.0 \
     --hash=sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d \
     --hash=sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2
-    # via mkdocs-material
+    # via
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
 backrefs==5.8 \
     --hash=sha256:2cab642a205ce966af3dd4b38ee36009b31fa9502a35fd61d59ccc116e40a6bd \
     --hash=sha256:2e1c15e4af0e12e45c8701bd5da0902d326b2e200cafcd25e49d9f06d44bb61b \
@@ -40,6 +42,14 @@ ghp-import==2.1.0 \
     --hash=sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619 \
     --hash=sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343
     # via mkdocs
+gitdb==4.0.12 \
+    --hash=sha256:5ef71f855d191a3326fcfbc0d5da835f26b13fbcba60c32c21091c349ffdb571 \
+    --hash=sha256:67073e15955400952c6565cc3e707c554a4eea2e428946f7a4c162fab9bd9bcf
+    # via gitpython
+gitpython==3.1.44 \
+    --hash=sha256:9e0e10cda9bed1ee64bc9a6de50e7e38a9c9943241cd7f585f6df3ed28011110 \
+    --hash=sha256:c87e30b26253bf5418b01b0660f818967f3c503193838337fe5e573331249269
+    # via mkdocs-git-revision-date-localized-plugin
 idna==3.10 \
     --hash=sha256:12f65c9b470abda6dc35cf8e63cc574b1c52b11df2c86030af0ac09b01b13ea9 \
     --hash=sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3
@@ -72,11 +82,17 @@ mergedeep==1.3.4 \
 mkdocs==1.6.1 \
     --hash=sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2 \
     --hash=sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e
-    # via mkdocs-material
+    # via
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
 mkdocs-get-deps==0.2.0 \
     --hash=sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c \
     --hash=sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134
     # via mkdocs
+mkdocs-git-revision-date-localized-plugin==1.4.7 \
+    --hash=sha256:056c0a90242409148f1dc94d5c9d2c25b5b8ddd8de45489fa38f7fa7ccad2bc4 \
+    --hash=sha256:10a49eff1e1c3cb766e054b9d8360c904ce4fe8c33ac3f6cc083ac6459c91953
+    # via -r requirements.in
 mkdocs-material==9.6.14 \
     --hash=sha256:39d795e90dce6b531387c255bd07e866e027828b7346d3eba5ac3de265053754 \
     --hash=sha256:3b9cee6d3688551bf7a8e8f41afda97a3c39a12f0325436d76c86706114b721b
@@ -113,6 +129,10 @@ python-dateutil==2.9.0.post0 \
     --hash=sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3 \
     --hash=sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427
     # via ghp-import
+pytz==2025.2 \
+    --hash=sha256:360b9e3dbb49a209c21ad61809c7fb453643e048b38924c765813546746e81c3 \
+    --hash=sha256:5ddf76296dd8c44c26eb8f4b6f35488f3ccbf6fbbd7adee0b7262d43f0ec2f00
+    # via mkdocs-git-revision-date-localized-plugin
 pyyaml==6.0.2 \
     --hash=sha256:8388ee1976c416731879ac16da0aff3f63b286ffdd57cdeb95f3f2e085687563 \
     --hash=sha256:d584d9ec91ad65861cc08d42e834324ef890a082e591037abe114850ff7bbc3e
@@ -133,6 +153,10 @@ six==1.17.0 \
     --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \
     --hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81
     # via python-dateutil
+smmap==5.0.2 \
+    --hash=sha256:26ea65a03958fa0c8a1c7e8c7a58fdc77221b8910f6be2131affade476898ad5 \
+    --hash=sha256:b30115f0def7d7531d22a0fb6502488d879e75b260a9db4d0819cfb25403af5e
+    # via gitdb
 urllib3==2.4.0 \
     --hash=sha256:414bc6535b787febd7567804cc015fee39daab8ad86268f1310a9250697de466 \
     --hash=sha256:4e16665048960a0900c702d4a66415956a584919c03361cac9f1df5c5dd7e813