From a6c0abdd39e39420fb2ee1fb1f90fb55e7405515 Mon Sep 17 00:00:00 2001 From: "MagicMock/mock.effective_git_name/140297175410272" Date: Tue, 24 Mar 2026 15:58:10 +0100 Subject: [PATCH 1/2] Add agents.md for AI-assisted development context Provides MkDocs setup, navigation conventions, blog post structure, and markdown extension usage for the documentation site. Co-Authored-By: Claude Opus 4.6 --- agents.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..8d8ca4b --- /dev/null +++ b/agents.md @@ -0,0 +1,58 @@ +# Documentation + +Developer and user documentation site for Freeshard, published at docs.freeshard.net. Built with MkDocs and the Material theme. + +## Tech Stack + +- **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) + +## Commands + +```bash +pip install -r requirements.txt # Install dependencies +mkdocs serve # Dev server on localhost:8000 +mkdocs build # Generate static site to public/ +``` + +## Structure + +``` +docs/ + overview/ Product overview and concepts + concepts/ Single-user isolation, devices, apps + developer_docs/ Developer documentation for app creators + includes/ Reusable markdown snippets (template vars, portal name info) + img/ Developer docs images + user_guides/ End-user guides (password management, smart home) + blog/ + posts/ Blog posts (date-prefixed directories) + YYYY-MM-DD_slug/ Each post: main.md + images + .authors.yml Blog author metadata + css/extra.css Custom styles + img/ Shared images (logo) +mkdocs.yml Site config, navigation, theme, plugins +``` + +## Conventions + +### Navigation +Navigation is explicitly defined in `mkdocs.yml` under the `nav` key. Four top-level sections: Overview, Developer Docs, Blog, User Guides. Adding a new page requires adding it to `nav`. + +### Blog Posts +Blog posts live in `docs/blog/posts/YYYY-MM-DD_slug/main.md`. Each post directory contains the markdown file and any associated images. Authors are defined in `docs/blog/.authors.yml`. + +### Markdown Includes +Reusable snippets in `docs/developer_docs/includes/` can be included in other docs via the `markdown-include` extension: `{!developer_docs/includes/snippet.md!}`. + +### Images +Store images alongside the content that uses them (in subdirectory `img/` or in blog post directories). Use relative paths. The glightbox plugin automatically adds lightbox behavior to images. + +### Mermaid Diagrams +Supported via `pymdownx.superfences` custom fence. Use ` ```mermaid ` code blocks. + +## Deployment + +Built and deployed via GitLab Pages. The `site_dir` is `public/` (GitLab Pages convention). Site URL: `https://docs.freeshard.net`. From 46683752afa790a0f4d24b55caa52ec6afdfd539 Mon Sep 17 00:00:00 2001 From: "MagicMock/mock.effective_git_name/140297175410272" Date: Tue, 24 Mar 2026 20:54:42 +0100 Subject: [PATCH 2/2] Fix CI: only deploy to GitHub Pages on pushes to main The deploy job's branch guard was commented out, causing it to run on PRs and non-main branches, which fails due to environment protection rules. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a69a1cc..5b03dbc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,7 +29,7 @@ jobs: path: public deploy: - # if: github.ref == 'refs/heads/main' + if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest needs: build permissions: