Merge pull request #9 from FreeshardBase/worktree-mkdocs-pin-ci

chore: pin docs toolchain and modernize CI image

Author: max-tet

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     container:
-      image: python:3.8-buster
+      image: python:3.12-slim
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitignore

@@ -2,5 +2,7 @@ public
 
 .idea
 
+.claude/worktrees
+
 venv
 .venv

agents.md

@@ -7,7 +7,7 @@ Developer and user documentation site for Freeshard, published at docs.freeshard
 - **Generator**: MkDocs with Material theme
 - **Plugins**: blog, glightbox (image lightbox)
 - **Markdown extensions**: admonitions, details, syntax highlighting, Mermaid diagrams, emoji, markdown-include
-- **Dependencies**: `requirements.txt` (mkdocs, mkdocs-material, markdown-include, mkdocs-glightbox)
+- **Dependencies**: `requirements.txt` (mkdocs, mkdocs-material, markdown-include, mkdocs-glightbox), pinned to exact versions — MkDocs 1.x is unmaintained and MkDocs 2.0 is not a viable upgrade (no plugin system, no Material support). Do not bump these; the migration target is Zensical, blocked on its blog plugin ([zensical/backlog#30](https://github.com/zensical/backlog/issues/30)).
 
 ## Commands
 
@@ -58,4 +58,4 @@ Supported via `pymdownx.superfences` custom fence. Use ` ```mermaid ` code block
 
 ## Deployment
 
-Built and deployed via GitLab Pages. The `site_dir` is `public/` (GitLab Pages convention). Site URL: `https://docs.freeshard.net`.
+Built and deployed via GitHub Pages (`.github/workflows/ci.yml`). Every push builds with `mkdocs build --strict`; pushes to `main` also deploy. The `site_dir` is `public/`. Site URL: `https://docs.freeshard.net`.

docs/blog/posts/2023-09-16_app_integration_overhaul/main.md

@@ -93,7 +93,7 @@ So to sum up, an app now consists of the following four artefacts:
 3. the `docker-compose.yml.template` which is a template for the `docker-compose.yml` file and
 4. an image file that is the app's icon.
 
-The docs contain all the details about the new app format [here](../../../developer_docs/overview.md#app-format){target=_blank}.
+The docs contain all the details about the new app format [here](../../../developer_docs/overview.md#the-apps-metadata){target=_blank}.
 
 And by the way, I of course also had to migrate all existing apps to the new format - or at least those that actually were used.
 

requirements.txt

@@ -1,9 +1,9 @@
 # Documentation static site generator & deployment tool
-mkdocs>=1.1.2
+mkdocs==1.6.1
 
 # Add your custom theme if not inside a theme_dir
 # (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
-mkdocs-material>=9.2.0b0
+mkdocs-material==9.7.6
 
-markdown-include
-mkdocs-glightbox
+markdown-include==0.8.1
+mkdocs-glightbox==0.5.2