Implement documentation quality commands

.github/workflows/quality.yml

@@ -53,5 +53,14 @@ jobs:
       - name: Check repository conformance
         run: uv run repo-quality check .
 
+      - name: Check documentation formatting
+        run: uv run check-docs-format
+
+      - name: Check documentation links
+        run: uv run check-docs-links
+
+      - name: Build documentation
+        run: uv run build-docs
+
       - name: Build distribution
         run: uv build

.gitignore

@@ -16,6 +16,7 @@ htmlcov/
 # Build output
 build/
 dist/
+site/
 
 # Editors and operating systems
 .idea/

AGENTS.md

@@ -35,14 +35,19 @@ must surface ambiguous policy rather than invent it.
 
 Run from the repository root:
 
-1. `uv sync --locked --all-groups`
-2. `uv run pre-commit run --all-files`
-3. `uv run ruff format --check .`
-4. `uv run ruff check .`
-5. `uv run ty check`
-6. `uv run pytest`
-7. `uv run repo-quality check .`
-8. `uv build`
+```bash
+uv sync --locked --all-groups
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+uv run repo-quality check .
+uv run check-docs-format
+uv run check-docs-links
+uv run build-docs
+uv build
+```
 
 CI must run the same validation commands. Do not bypass a failed gate or edit
 generated files to hide a mismatch.

CHANGELOG.md

@@ -12,6 +12,7 @@ semantic versioning once the first stable release is published.
   repositories.
 - Self-auditing `repo-quality check` CLI.
 - Golden-reference CI, tests, contributor guidance, and security policy.
+- Executable documentation formatting, link-checking, and site-build commands.
 
 ### Changed
 

README.md

@@ -21,6 +21,9 @@ Install the development environment and verify this repository:
 ```bash
 uv sync --locked --all-groups
 uv run repo-quality check .
+uv run check-docs-format
+uv run check-docs-links
+uv run build-docs
 uv run pytest
 ```
 
@@ -64,6 +67,11 @@ provide fast feedback, while CI runs the authoritative locked gate chain. See
 [Quality Gates](docs/quality-gates.md) for universal, profile-specific, and
 conditional gates.
 
+The documentation commands are installed with the package. They check Markdown
+formatting, validate local links and heading fragments, retry external link
+checks, and build a strict MkDocs site. Known external exceptions can be made
+explicit with repeatable `--exclude-url-prefix` arguments.
+
 ## Repository Layout
 
 ```text
@@ -75,6 +83,7 @@ conditional gates.
 |-- tests/                   # Behavior and conformance tests
 |-- AGENTS.md                # Instructions for coding agents
 |-- CONTRIBUTING.md          # Human contribution workflow
+|-- mkdocs.yml               # Strict documentation-site configuration
 |-- SECURITY.md              # Vulnerability reporting and security boundary
 |-- pyproject.toml           # Package and tool configuration
 |-- repo-quality.toml        # Declared profile and quality contract

SECURITY.md

@@ -19,3 +19,9 @@ workaround. Do not include real credentials or sensitive production data.
 The `repo-quality` CLI reads repository files and reports findings. It does not
 execute commands declared in `repo-quality.toml`, install dependencies, access
 the network, or modify the target repository.
+
+`check-docs-links` makes outbound HEAD or GET requests to HTTP(S) targets found
+in Markdown unless `--no-external` is set. `build-docs` runs MkDocs and replaces
+the configured site output directory, which is `site/` in this repository.
+Review configuration and link targets before running these commands against an
+untrusted repository.

docs/index.md

@@ -0,0 +1,15 @@
+# Repository Quality Reference
+
+This documentation defines a small, executable quality standard for repositories
+maintained by humans and coding agents. Python and `uv` are the maintained default
+language and tooling ecosystem.
+
+## Start Here
+
+- Read the [standard](standard.md) for normative requirements.
+- Choose a supported [repository shape](repository-shapes.md).
+- Adopt the appropriate [quality gates](quality-gates.md).
+- Use the [adoption guide](adoption.md) to introduce the standard incrementally.
+
+The project README contains installation and command examples. This site holds the
+durable standard, operating guidance, and architectural decisions.

docs/quality-gates.md

@@ -73,6 +73,21 @@ A documentation repository MUST define equivalents for:
 The exact tools are repository decisions. Python-based tooling managed through
 `uv` is preferred to preserve the default ecosystem and a single lock file.
 
+This reference package provides a maintained default command set:
+
+```bash
+uv run check-docs-format
+uv run check-docs-links
+uv run build-docs
+```
+
+`check-docs-format` runs mdformat in check mode with consistent ordered-list
+numbering. `check-docs-links` validates local targets and heading fragments,
+checks each unique external HTTP(S) target, and retries transient failures twice.
+Repositories MAY exclude a known external URL prefix with
+`--exclude-url-prefix` when the exception is intentional and visible in the CI
+command. `build-docs` runs a strict MkDocs build using `mkdocs.yml`.
+
 ## Conditional Gates
 
 Add these only when the repository has the associated failure mode:

docs/repository-shapes.md

@@ -29,6 +29,7 @@ runbooks, architecture guidance, or a knowledge base.
 |-- tools/                    # optional Python doc tooling
 |-- AGENTS.md
 |-- README.md
+|-- mkdocs.yml                # when a documentation site is built
 |-- pyproject.toml            # when Python tooling is used
 `-- uv.lock                   # when Python tooling is used
 ```

examples/doc-only/repo-quality.toml

@@ -2,7 +2,7 @@ schema_version = 1
 
 [repository]
 purpose = "doc-only"
-required_paths = ["CONTRIBUTING.md"]
+required_paths = ["CONTRIBUTING.md", "mkdocs.yml"]
 
 [documentation]
 readme_sections = ["Purpose", "Navigation", "Contributing"]

mkdocs.yml

@@ -0,0 +1,26 @@
+site_name: Repository Quality Reference
+site_description: Portable quality profiles for Python-first repositories
+repo_url: https://github.com/JayTeeBat/repo-quality-reference
+docs_dir: docs
+site_dir: site
+strict: true
+
+theme:
+  name: mkdocs
+
+nav:
+  - Overview: index.md
+  - Standard: standard.md
+  - Repository Shapes: repository-shapes.md
+  - Quality Gates: quality-gates.md
+  - README and AGENTS: readme-and-agents.md
+  - Repository Lifecycle: lifecycle.md
+  - Adoption: adoption.md
+  - Architecture Decisions:
+      - Index: adr/README.md
+      - Self-Auditing Reference: adr/0001-self-auditing-reference.md
+
+validation:
+  links:
+    anchors: warn
+    unrecognized_links: warn

pyproject.toml

@@ -9,11 +9,17 @@ authors = [
   { name = "Jacques Thomazo" },
 ]
 dependencies = [
+  "markdown>=3.10,<4",
   "markdown-it-py>=3.0.0,<5",
+  "mdformat>=1.0.0,<2",
+  "mkdocs>=1.6.1,<2",
   "pyyaml>=6.0.2,<7",
 ]
 
 [project.scripts]
+build-docs = "repo_quality.docs:build_main"
+check-docs-format = "repo_quality.docs:format_main"
+check-docs-links = "repo_quality.docs:links_main"
 repo-quality = "repo_quality.cli:main"
 
 [dependency-groups]

repo-quality.toml

@@ -7,6 +7,7 @@ required_paths = [
   "CHANGELOG.md",
   "CONTRIBUTING.md",
   "LICENSE",
+  "mkdocs.yml",
   "SECURITY.md",
   "docs/adr",
   "examples",
@@ -39,5 +40,8 @@ commands = [
   "uv run ty check",
   "uv run pytest",
   "uv run repo-quality check .",
+  "uv run check-docs-format",
+  "uv run check-docs-links",
+  "uv run build-docs",
   "uv build",
 ]