chore(docs): drop Insiders and consolidate to open Material#21
Merged
Conversation
- Merge outsiders Mermaid setup into mkdocs.yml (mermaid2 + JS) - Always use mkdocs.yml in Makefile; remove Insiders token logic - Always install open mkdocs-material via Poetry - Remove mkdocs.insiders.yml and mkdocs.outsiders.yml Simplifies builds to free Material and reduces config drift.
- Move dependencies to [project.dependencies] and set license file - Remove Poetry/asdf-poetry; install and use uv - Use 'uv venv' + 'uv sync'; run mkdocs via 'uv run' - Drop Poetry from .tool-versions
Remove obsolete local 'act' helper; not used in current workflow.
- Update .tool-versions to 3.13.1 (asdf) - Set requires-python to ">=3.13" in pyproject - Align Makefile fallback var to 3.13
- Drop unused PIP variables - Info target prints mkdocs version using `uv run`
- Use `command -v python3` for SYSTEM_PYTHON on macOS/Linux - Bump actions/setup-python to v5 and 3.13
Force `uv venv --python 3.13` to avoid accidental 3.14 picks on hosts with newer system interpreters; keeps env aligned with asdf/CI.
- Reorder docs-install so venv/deps are set up before info - Ensure venv step recreates with Python 3.13 when mismatched - Avoid interactive prompts by setting UV_VENV_CLEAR=1 - Install packages via `uv sync` only
- Switch from materialx.emoji.* to material.extensions.emoji.* (Material >=9.4) - Rename kroki options to snake_case (server_url, download_images, download_dir)
Newer mkdocs-kroki-plugin no longer supports download_dir; rely on server rendering only.
Ensures mkdocs-include-markdown finds files consistently in strict mode.
- Use root-relative include paths for build step summaries - Replace trailing-slash links with explicit .md doc links
Resolve strict include failure for Envision/Discover/Assess/Train/Chart.
Resolve strict include failure for run phase pages.
Removes yellow banner advising to use !option handwritten.
- Disable shadows, reduce round corners to 8 - Use Roboto font to match site - Thinner sequence borders - Handwritten already disabled via !option
Ensures PlantUML diagrams are regenerated after theme changes.
… font size - Add `!option handwritten false` at top of each .puml - Bump default FontSize to 14 for better readability
Ensures PlantUML processes the non-handwritten directive globally.
Force both !option and skinparam handwritten false to eliminate wavy edges.
- Switch PlantUML back to server rendering (avoid CI complexity) - Fix all absolute links to use relative paths with .md extensions - Fix relative links to include proper .md extensions for strict mode - Remove broken links to non-existent dataset.md file - Update Mermaid config to use plugin's javascript option (fix deprecation) - Remove PAT_MKDOCS_INSIDERS references from GitHub workflow - Update GitHub Actions to latest versions (checkout@v4, cache@v4) - Fix all link warnings to ensure clean builds in strict mode
- Remove condition from 'Install all MkDocs dependencies' step so it runs on PRs - This fixes 'uv: command not found' error when building PRs - Build step runs on all branches/PRs to validate changes - Deploy step only runs on main branch after successful build - Add clarifying comments to workflow steps
- Add .vscode/settings.json for Makefile configuration - Add charter/proposed-charter.md for Use Case Tree Workgroup - Add uv.lock for dependency locking
- Update asdf-vm/actions/install from v2 to v3 - Makefile now checks if asdf is already installed before installing via Homebrew - This avoids duplicate installations and reduces migration warnings in CI
- Upgrade from v3 to v4 which supports asdf >= v0.16.0 - This should eliminate migration notice warnings in CI logs
- Cache asdf installations (~/.asdf/installs, plugins, shims) based on .tool-versions - Cache uv package cache and Python venv based on uv.lock/pyproject.toml - Remove old main-branch-only cache - Caching now works for all branches and PRs to speed up builds
- Convert all labels to use proper match object format with 'any:' and 'changed-files:' - Fix mkdocs-infra label that was causing 'unexpected type' error - Consolidate agnos-ai patterns into single 'any:' block
- Fixes 'Expected string' YAML validation error - File doesn't exist in the repository
- PlantUML requires Java (already in .tool-versions), not Node.js - No npm packages or Node.js tools are used in the project - All dependencies are Python-based
- PlantUML is configured with render: 'server' using http://www.plantuml.com/plantuml - No local Java or PlantUML binary needed for server-side rendering - This speeds up CI builds by removing unnecessary dependencies
- Already removed from Makefile in previous commit - Completes the removal of Java dependency
- Use 'any-glob-to-any-file' key with array of patterns - Fixes 'changed-files section must have valid config structure' error
jgeluk
added a commit
that referenced
this pull request
Dec 1, 2025
* chore(docs): drop Insiders and consolidate to single mkdocs config - Merge outsiders Mermaid setup into mkdocs.yml (mermaid2 + JS) - Always use mkdocs.yml in Makefile; remove Insiders token logic - Always install open mkdocs-material via Poetry - Remove mkdocs.insiders.yml and mkdocs.outsiders.yml Simplifies builds to free Material and reduces config drift. * chore(build): replace Poetry with uv and PEP 621 deps - Move dependencies to [project.dependencies] and set license file - Remove Poetry/asdf-poetry; install and use uv - Use 'uv venv' + 'uv sync'; run mkdocs via 'uv run' - Drop Poetry from .tool-versions * chore(ci): remove local GH Actions helper script act.sh Remove obsolete local 'act' helper; not used in current workflow. * chore(python): bump to Python 3.13 - Update .tool-versions to 3.13.1 (asdf) - Set requires-python to ">=3.13" in pyproject - Align Makefile fallback var to 3.13 * chore(build): remove pip remnants; show mkdocs via uv in info - Drop unused PIP variables - Info target prints mkdocs version using `uv run` * chore(build): fix System Python detection; CI to Python 3.13 - Use `command -v python3` for SYSTEM_PYTHON on macOS/Linux - Bump actions/setup-python to v5 and 3.13 * chore(build): pin uv venv to Python 3.13 Force `uv venv --python 3.13` to avoid accidental 3.14 picks on hosts with newer system interpreters; keeps env aligned with asdf/CI. * chore(build): make install non-interactive and show correct versions - Reorder docs-install so venv/deps are set up before info - Ensure venv step recreates with Python 3.13 when mismatched - Avoid interactive prompts by setting UV_VENV_CLEAR=1 - Install packages via `uv sync` only * fix(mkdocs): update emoji extensions and kroki options for strict mode - Switch from materialx.emoji.* to material.extensions.emoji.* (Material >=9.4) - Rename kroki options to snake_case (server_url, download_images, download_dir) * fix(kroki): drop removed download_dir option (strict mode) Newer mkdocs-kroki-plugin no longer supports download_dir; rely on server rendering only. * fix(docs): use root-relative include paths in objective/index Ensures mkdocs-include-markdown finds files consistently in strict mode. * fix(docs): resolve strict include and link warnings in process section - Use root-relative include paths for build step summaries - Replace trailing-slash links with explicit .md doc links * fix(docs): root-relative includes and links in plan/index Resolve strict include failure for Envision/Discover/Assess/Train/Chart. * fix(docs): root-relative includes in run/index Resolve strict include failure for run phase pages. * fix(plantuml): replace deprecated 'skinparam handwritten' with '!option' Removes yellow banner advising to use !option handwritten. * style(plantuml): modernize theme (flat, smaller radius, Roboto) - Disable shadows, reduce round corners to 8 - Use Roboto font to match site - Thinner sequence borders - Handwritten already disabled via !option * chore(make): add docs-diagrams-clean and docs-serve-fresh to refresh UML Ensures PlantUML diagrams are regenerated after theme changes. * style(plantuml): force non-handwritten mode in all diagrams; increase font size - Add `!option handwritten false` at top of each .puml - Bump default FontSize to 14 for better readability * fix(plantuml): move '!option handwritten false' before @startuml Ensures PlantUML processes the non-handwritten directive globally. * fix(plantuml): add explicit skinparam handwritten false at top Force both !option and skinparam handwritten false to eliminate wavy edges. * Fix MkDocs warnings and update configuration - Switch PlantUML back to server rendering (avoid CI complexity) - Fix all absolute links to use relative paths with .md extensions - Fix relative links to include proper .md extensions for strict mode - Remove broken links to non-existent dataset.md file - Update Mermaid config to use plugin's javascript option (fix deprecation) - Remove PAT_MKDOCS_INSIDERS references from GitHub workflow - Update GitHub Actions to latest versions (checkout@v4, cache@v4) - Fix all link warnings to ensure clean builds in strict mode * Fix GitHub workflow: install dependencies for PR builds - Remove condition from 'Install all MkDocs dependencies' step so it runs on PRs - This fixes 'uv: command not found' error when building PRs - Build step runs on all branches/PRs to validate changes - Deploy step only runs on main branch after successful build - Add clarifying comments to workflow steps * Add project files: VS Code settings, charter, and uv lock file - Add .vscode/settings.json for Makefile configuration - Add charter/proposed-charter.md for Use Case Tree Workgroup - Add uv.lock for dependency locking * Update asdf action to v3 and improve Makefile asdf detection - Update asdf-vm/actions/install from v2 to v3 - Makefile now checks if asdf is already installed before installing via Homebrew - This avoids duplicate installations and reduces migration warnings in CI * Update asdf action to v4 for asdf 0.16+ support - Upgrade from v3 to v4 which supports asdf >= v0.16.0 - This should eliminate migration notice warnings in CI logs * Add comprehensive caching for asdf tools and uv dependencies - Cache asdf installations (~/.asdf/installs, plugins, shims) based on .tool-versions - Cache uv package cache and Python venv based on uv.lock/pyproject.toml - Remove old main-branch-only cache - Caching now works for all branches and PRs to speed up builds * Fix labeler.yml configuration format - Convert all labels to use proper match object format with 'any:' and 'changed-files:' - Fix mkdocs-infra label that was causing 'unexpected type' error - Consolidate agnos-ai patterns into single 'any:' block * Remove non-existent docs/main.py from labeler config - Fixes 'Expected string' YAML validation error - File doesn't exist in the repository * Remove Node.js as it's no longer used - PlantUML requires Java (already in .tool-versions), not Node.js - No npm packages or Node.js tools are used in the project - All dependencies are Python-based * Remove Java and PlantUML as we use external PlantUML server - PlantUML is configured with render: 'server' using http://www.plantuml.com/plantuml - No local Java or PlantUML binary needed for server-side rendering - This speeds up CI builds by removing unnecessary dependencies * Remove Java from .tool-versions - Already removed from Makefile in previous commit - Completes the removal of Java dependency * Fix labeler.yml format to use correct changed-files structure - Use 'any-glob-to-any-file' key with array of patterns - Fixes 'changed-files section must have valid config structure' error --------- Co-authored-by: Jacobus Geluk <jgeluk@jg2.local>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs.yml(mermaid2+ JS include)Makefileto always usemkdocs.ymland install openmkdocs-materialmkdocs.insiders.ymlandmkdocs.outsiders.ymlRationale
Reduces config drift and removes license dependency while retaining features (Mermaid, PlantUML via Kroki/PlantUML plugin, search, overrides, Giscus).
Test plan