Add opinionated MkDocs + GitHub Pages docs tooling to template

.github/workflows/test.yml

@@ -45,6 +45,13 @@ jobs:
       - run: uv run ./demo/manage.py check
       - run: uv run ./demo/manage.py makemigrations --check --noinput
       - run: uv run ./demo/manage.py test home
+      - run: just docs-build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+          # Required so the `.well-known/agent-skills/` and `.well-known/ai-catalog.json`
+          # files generated by docs/hooks.py are included in the Pages artifact.
+          include-hidden-files: true
 
   test-lowest-deps:
     runs-on: ubuntu-latest
@@ -92,3 +99,17 @@ jobs:
       - run: uv run --resolution ${{ matrix.resolution }} --with '${{ matrix.packages }}' pytest
         env:
           DB: sqlite
+
+  deploy-docs:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      pages: write # to deploy to GitHub Pages
+      id-token: write # to verify the deployment originates from a trusted source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        id: deployment

.prettierignore

@@ -10,5 +10,6 @@ _build
 *.md
 # Files which contain incompatible syntax.
 *.html
+/site
 .mypy_cache
 /coverage_html_report

.stylelintignore

@@ -9,3 +9,4 @@ _build
 /coverage_html_report
 /htmlcov
 /demo
+/site

AGENTS.md

@@ -22,4 +22,6 @@ just test       # Run tests with pytest
 just lint       # Run all linters (Ruff, prek, Prettier, Stylelint)
 just format     # Run all formatters (Ruff, Prettier)
 just coverage   # Run tests with coverage report
+just docs-build # Build the documentation site (strict mode)
+just docs-serve # Build and serve the documentation locally
 ```

CONTRIBUTING.md

@@ -36,6 +36,8 @@ Here are the available tooling scripts for the project:
 just clean-pyc         # Remove all the Python and Node.js cache files.
 just coverage          # Run tests with coverage.
 just demo              # Run the demo application.
+just docs-build        # Build the documentation site (strict mode).
+just docs-serve        # Build and serve the documentation locally.
 just format            # Run all formatters.
 just format-client     # Format the client code with Prettier.
 just format-server     # Format the server code with uv.

README.md

@@ -17,6 +17,7 @@ The generated package contains:
 - A `demo/` Wagtail site with home, blog, and search apps, ready to run with `just demo`.
 - A `tests/` directory with pytest and pytest-django configured, and a placeholder test.
 - A `justfile` with recipes for linting, formatting, testing, coverage, and running the demo.
+- A documentation site built with [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), with an API reference generated from docstrings via [mkdocstrings](https://mkdocstrings.com/) and published to GitHub Pages (`just docs-build` / `just docs-serve`).
 - Project configuration with `pyproject.toml` (uv build backend), `ruff.toml`, `prek.toml`, Prettier, and Stylelint.
 
 ### CI

cookiecutter.json

@@ -5,9 +5,12 @@
   "__project_name_camel": "{{ cookiecutter.__project_name_snake.replace('_', ' ').title().replace(' ', '') }}",
   "project_short_description": "A cool description with important information",
   "repository_url": "https://github.com/org-name-or-username/my-project-name",
+  "__project_org": "{{ cookiecutter.repository_url.split('/')[3] }}",
+  "__project_site_url": "https://{{ cookiecutter.__project_org }}.github.io/{{ cookiecutter.__project_name_kebab }}/",
   "_copy_without_render": [
     ".github/workflows",
     "demo/*/templates",
-    "src/*/templates"
+    "src/*/templates",
+    "docs/theme"
   ]
 }

docs/README.md

@@ -10,6 +10,8 @@ The repository root contains the full, runnable package:
 ├── src/my_project_name/   # The Django app (source code)
 ├── tests/                 # Test suite
 ├── demo/                  # Demo Wagtail site
+├── docs/                  # MkDocs site source (Markdown pages)
+├── mkdocs.yml             # Documentation configuration
 ├── .github/workflows/     # CI configuration
 ├── justfile               # Task runner recipes
 ├── pyproject.toml         # Package metadata and build config

docs/agent-skills.md

@@ -0,0 +1,23 @@
+# Agent skills
+
+My project name ships [agent skills](https://agentskills.io/) that help agents get better results with agentic coding. They are published with the documentation site so they can be discovered and reused with a wide range of tools.
+
+## Editing the skills
+
+Skills live under `src/my_project_name/.agents/skills/`. The template ships one placeholder skill you can replace or extend. Edit the `SKILL.md` files there; the post-build hook in `docs/hooks.py` publishes them automatically.
+
+## Direct link to the skill
+
+The published skill is served from the documentation site at `.well-known/agent-skills/my-project-name/SKILL.md`. Open the URL to read the skill, point an agent at it, or download it and place it in `.agents/skills/my-project-name/SKILL.md` in your project so tooling that reads local skills picks it up.
+
+## Well Known Discovery
+
+Machine-readable index of all skills: `/.well-known/agent-skills/index.json`. This is per the [Well Known Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc). Agents that support the format can fetch it to discover the skills.
+
+## AI catalog
+
+Machine-readable index that also covers options other than skills: `/.well-known/ai-catalog.json`. This is per the [AI Catalog](https://ai-catalog.io/) specification.
+
+## How it works
+
+During the documentation build, `mkdocs-simple-hooks` runs `docs/hooks.py:on_post_build`, which copies each skill and generates both discovery catalogs. Set `include-hidden-files: true` on the Pages upload in `.github/workflows/test.yml` so the `.well-known/` directory is included in the deployed artifact.

docs/contributing/documentation.md

@@ -0,0 +1,77 @@
+# Documentation & tooling
+
+This page explains how the project's documentation is built, how to write and maintain it, and the reasoning behind the tooling choices.
+
+## How the docs are built
+
+The documentation site is built with [MkDocs](https://www.mkdocs.org/) using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, and published to [GitHub Pages](https://pages.github.com/). Source files live in `docs/` at the repository root, and the site config is `mkdocs.yml`.
+
+Two commands drive local development:
+
+```sh
+just docs-build    # Build the site into `site/`, failing on any warning (strict mode).
+just docs-serve    # Build and serve the site at http://localhost:8001 with live reload.
+```
+
+On every push to `main`, CI builds the documentation in [strict mode](https://www.mkdocs.org/user-guide/configuration/#strict) and deploys the result to GitHub Pages.
+
+### Why MkDocs over Sphinx
+
+| Tool | MkDocs | Sphinx | Zensical |
+|---|---|---|---|
+| Language | Markdown | reStructuredText / Markdown | Markdown |
+| Python API reference | [mkdocstrings](https://mkdocstrings.com/) | [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) | Marketing-oriented |
+| Default theme quality | Material (excellent, modern) | Read the Docs / Furo | Hosted |
+| Configuration burden | Low, YAML-only | High (`conf.py`, reStructuredText quirks) | Low (no self-hosting) |
+| Ecosystem maturity | Large plugin set | Largest, mature | Small |
+
+MkDocs was chosen because the Material theme removes most of the effort required to get a polished, responsive site, and markdown is easier for contributors to write correctly than reStructuredText. `mkdocstrings` provides first-class extraction of API references from Python docstrings, matching Sphinx's `autodoc` without the configuration overhead.
+
+### Why GitHub Pages over Read the Docs
+
+| Host | GitHub Pages | Read the Docs |
+|---|---|---|
+| Cost | Free | Free |
+| Access to source | Lives with the code, deploys from CI | Separate account + service |
+| Custom domains | Supported | Supported |
+| Versioned docs | Manual "latest/stable" (by branch) | Built-in "latest"/"stable" |
+| Build dependencies | Fully controlled by your own CI | Limited to their build environment |
+
+GitHub Pages is chosen because the deployment already happens in the repository's own CI, keeping docs builds in lockstep with the exact Python toolchain the project uses. For packages in the early template's target (single maintained branch), the added "stable" vs "latest" routing on Read the Docs offers little value over just publishing `main`. Documentation deploys on a push to `main`, so docs always match the current code.
+
+## Evaluation criteria
+
+When this setup was chosen, the options were compared against these criteria:
+
+- **Ease of use** – how quickly a new contributor can write docs and get a preview. Favours Markdown and a curated default theme.
+- **Support for docstrings / docs from Python code** – how well the tool can turn source docstrings into an API reference. Favours `mkdocstrings` / `autodoc`.
+- **Deployment fit** – how much friction there is to publish, and whether the build runs in the project's own CI.
+- **Maturity** – longevity, plugin ecosystem, and the size of the community maintaining it.
+
+## Writing documentation
+
+- Put pages in `docs/` and register them in `nav:` inside `mkdocs.yml`. A page not listed in `nav:` will not be part of the site.
+- Follow the Material theme's [Markdown extensions](https://squidfunk.github.io/mkdocs-material/reference/) for admonitions, tabs, code annotations, and checklists. They are already enabled in `mkdocs.yml`.
+- Cross-link pages with relative links (e.g. `[Usage](usage.md)`).
+- Keep examples copy-pasteable and taken from the package's real code.
+- Run `just docs-build` before pushing; strict mode fails the build on any warning, including broken links and unreadable reference directives.
+
+## Keeping docstrings in sync
+
+The [API reference](../reference/api.md) is generated from source docstrings with `mkdocstrings`, using `::: module.path.symbol` directives. Because this template relies on a placeholder for the package name, write docstrings in the package's source code and let CI catch drift — if a directive can't be resolved, `just docs-build` fails.
+
+When a public API member is added or renamed, update `docs/reference/api.md` accordingly and verify with `just docs-build`.
+
+## LLM-friendly output
+
+The `mkdocs-llmstxt` plugin generates `llms.txt` and `llms-full.txt` in the built site, a Markdown digest of the docs tailored for LLMs and agents (per [llms.txt](https://llmstxt.org/)). Configure the included pages via the `llmstxt.sections` setting in `mkdocs.yml`. Because these are served from GitHub Pages, the digest is available at the site root, e.g. `https://your-org.github.io/my-project-name/llms.txt`.
+
+## Agent skill discovery
+
+Like the reference implementation this is based on ([draftjs_exporter](https://github.com/wagtail/draftjs_exporter)), the docs publish the package's own [agent skills](https://agentskills.io/) under `.well-known/agent-skills/` and `.well-known/ai-catalog.json`. Skills live under `src/my_project_name/.agents/skills/` (one directory per skill, each containing a `SKILL.md`), and an `on_post_build` hook (`docs/hooks.py`) copies them into the site and generates both discovery catalogs.
+
+The hook reads host metadata from the `site_url` in `mkdocs.yml`, so no URLs are hardcoded. A placeholder skill is scaffolded by the template; edit or replace it in `src/my_project_name/.agents/skills/`. See the [Agent skills](../agent-skills.md) page for the published endpoints, and note that `.github/workflows/test.yml` sets `include-hidden-files: true` on the Pages upload so the `.well-known/` files are deployed.
+
+## Contributing to these docs
+
+Make changes to the relevant Markdown file in `docs/` or to `mkdocs.yml`, then verify with `just docs-build`. See the [contributing guidelines](https://github.com/org-name-or-username/my-project-name/blob/main/CONTRIBUTING.md) for the general workflow.

docs/getting-started.md

@@ -0,0 +1,74 @@
+# Getting started
+
+My project name is a reusable Wagtail package. The fastest way to try it is with the included demo site. For your own project, install the package and add it to your Django settings.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Django 5.2 or newer.
+- Wagtail 7 or newer.
+
+## Try the demo site
+
+Clone the repository and run the bundled demo to see the package in action:
+
+```sh
+just install
+just demo
+```
+
+This runs database migrations, loads initial data, and starts a local server. Open the site at <http://localhost:8000/> and the admin at <http://localhost:8000/admin/>.
+
+## Install in your project
+
+Install the package with pip:
+
+```sh
+pip install my-project-name
+```
+
+Then add the app to `INSTALLED_APPS` in your Django settings:
+
+```python
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "wagtail",
+    "wagtail.contrib.forms",
+    "wagtail.contrib.redirects",
+    "wagtail.contrib.settings",
+    "wagtail.embeds",
+    "wagtail.sites",
+    "wagtail.users",
+    "wagtail.snippets",
+    "wagtail.documents",
+    "wagtail.images",
+    "wagtail.search",
+    "wagtail.admin",
+    "wagtail.models",
+    "wagtail.api.v2",
+    "wagtail.contrib.routable_page",
+    "wagtail.contrib.styleguide",
+    "modelcluster",
+    "taggit",
+    # Third-party apps.
+    "my_project_name",
+    # Your project's apps.
+]
+```
+
+Run the migration to create any database objects the package needs:
+
+```sh
+python manage.py migrate
+```
+
+## Next steps
+
+- [Usage](usage.md) – configuration, settings, and template integration.
+- [API reference](reference/api.md) – the full public API.
+- [Configuration](reference/configuration.md) – settings and Wagtail hooks.