From 09c921592069a852083b7d727bc86ca2e2ea2a08 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Sat, 25 Jul 2026 11:46:23 +0000 Subject: [PATCH 1/2] chore: pin docs toolchain and modernize CI image MkDocs 1.x is unmaintained and MkDocs 2.0 drops the plugin system and Material theme support entirely, so it is not an upgrade path for this site. The likely successor is Zensical, but it does not support the blog plugin yet, so we stay on the current stack for now. Pin all four dependencies to the versions currently in use so an upstream release cannot change what CI builds while the toolchain is frozen. Bump the CI container from python:3.8-buster (EOL October 2024) to python:3.12-slim. Zensical requires Python >=3.10, so this also removes a blocker for the eventual migration. Fix a broken anchor in the 2023 app-integration post: the linked #app-format section does not exist in developer_docs/overview.md; the app format is described under "The App's metadata". Also gitignore .claude/worktrees so agent worktrees are not swept into commits. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/ci.yml | 2 +- .gitignore | 2 ++ .../posts/2023-09-16_app_integration_overhaul/main.md | 2 +- requirements.txt | 8 ++++---- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b03dbc..5a829fc 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 0964e58..2ca68d0 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,7 @@ public .idea +.claude/worktrees + venv .venv diff --git a/docs/blog/posts/2023-09-16_app_integration_overhaul/main.md b/docs/blog/posts/2023-09-16_app_integration_overhaul/main.md index 5a0508a..1570ad0 100644 --- a/docs/blog/posts/2023-09-16_app_integration_overhaul/main.md +++ b/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. diff --git a/requirements.txt b/requirements.txt index 496653b..3735f87 100644 --- a/requirements.txt +++ b/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 From 1ce16c2c32eac6b14874fea24e80e9dab8879f71 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Sat, 25 Jul 2026 11:55:01 +0000 Subject: [PATCH 2/2] docs: correct deployment target in agents.md The site deploys to GitHub Pages via .github/workflows/ci.yml, not GitLab Pages. Also record that the toolchain is pinned deliberately, so future agents do not "helpfully" bump MkDocs. Co-Authored-By: Claude Opus 5 (1M context) --- agents.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/agents.md b/agents.md index 8af6fc2..ed13d27 100644 --- a/agents.md +++ b/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`.