A short website that gets people running, checked against the code in CI

.github/CONTRIBUTING.md

@@ -95,13 +95,14 @@ a known fix.
 These are exactly what continuous integration runs, and running them locally
 first is the difference between one review round and three. The first three are
 the CI workflow, in the order it runs them; the fourth belongs to the
-documentation workflow and only fires when the documentation changed:
+documentation workflow and only fires when the website or the code it describes
+changed:
 
 ```bash
 cargo fmt --all -- --check
 cargo clippy --locked --all-targets -- -D warnings
 RECORE_REQUIRE_MINIMAP2=1 cargo test --locked --all-targets
-mkdocs build --strict          # only if you touched docs/ or mkdocs.yml
+python3 tools/check_site.py --recore target/debug/recore --run-tutorial  # docs/ or the CLI
 ```
 
 Three things about that list are worth explaining, because they are not the
@@ -180,7 +181,7 @@ python3 -m http.server 8000 --directory out/
 | `tests/integration.rs` | the end-to-end run, the one that needs minimap2 |
 | `benchmarks/` | Python benchmarks and the tutorial dataset generator |
 | `tools/` | `make_logo_variants.py`, which generates the logo variants and the report's dark-mode colour overrides |
-| `docs/` | the MkDocs Material site |
+| `docs/` | the website (plain HTML, no build step) and the long-form markdown pages |
 | `.github/workflows/` | CI, documentation build, release builds |
 
 Recore is a Rust command-line tool and nothing else. There is no desktop
@@ -234,15 +235,13 @@ you anything tends not to get run.
 
 ## Documentation
 
-```bash
-pip install -r requirements-docs.txt
-mkdocs serve
-```
-
-The documentation workflow builds with `mkdocs build --strict`, which turns a
-broken internal link or a page missing from the `nav` into a build failure
-instead of a dead link somebody finds six months later. Adding a page means
-adding it to `nav` in `mkdocs.yml`.
+The website is plain HTML in `docs/` (`index.html`, `reference.html` and
+`assets/`), with no build step: open `docs/index.html` to see a change. The
+documentation workflow runs `tools/check_site.py`, which fails on a dead link or
+anchor, an option `recore --help` does not have, an option missing from the
+reference, a default that differs from the binary's, or an example run whose
+counts differ from the page's, instead of a stale page somebody finds six
+months later. The long-form pages are markdown under `docs/` and read on GitHub.
 
 `docs/assets/example-report.html` is the tutorial run's own output, linked from
 the [Run report](../docs/guide/report.md) page. If you change the viewer, that

.github/ISSUE_TEMPLATE/config.yml

@@ -3,10 +3,10 @@
 # put them is worse than an unstructured issue.
 blank_issues_enabled: true
 
-# The documentation links point at the markdown files in this repository rather
-# than at the built site. The MkDocs site exists and CI builds it on every push
-# to main, but GitHub Pages needs a public repository or a paid plan, and this
-# repository is private on the free plan, so the published URL would be a dead
+# The documentation links point at the files in this repository rather than at
+# a published site. The website in docs/ is plain HTML that GitHub Pages can
+# serve as it is, but Pages needs a public repository or a paid plan, and this
+# repository is private on the free plan, so a published URL would be a dead
 # link on the busiest page in the tracker. GitHub renders these files in place,
 # so the links work today and can be swapped for the site URL the day Pages is
 # available.

.github/dependabot.yml

@@ -64,37 +64,6 @@ updates:
         patterns: ["*"]
         update-types: ["major"]
 
-  # The documentation site's build dependencies.
-  #
-  # The directory is "/" and not "/docs" because that is where
-  # `requirements-docs.txt` actually lives. Dependabot finds it by reading the
-  # requirements-shaped `.txt` files in the directory rather than by matching a
-  # fixed filename, so the name being unusual costs nothing, but the directory
-  # being wrong would cost everything: a `pip` entry pointed at a directory with
-  # no requirements file in it does not fail, it simply never opens anything.
-  #
-  # This is the one ecosystem whose pull requests are checked by the docs build
-  # as well as by CI, because `requirements-docs.txt` is in the path filter of
-  # .github/workflows/docs.yml. The pin is `>=9.6,<10`, so mkdocs-material 10
-  # arrives as a major that widens that range, and a major of the theme is
-  # exactly the change that turns `mkdocs build --strict` red over a renamed
-  # option. That one waits for a person; the 9.x releases do not.
-  - package-ecosystem: pip
-    directory: "/"
-    schedule:
-      interval: monthly
-    open-pull-requests-limit: 2
-    labels: ["dependencies", "documentation"]
-    commit-message:
-      prefix: "docs"
-    groups:
-      docs-routine:
-        patterns: ["*"]
-        update-types: ["minor", "patch"]
-      docs-major:
-        patterns: ["*"]
-        update-types: ["major"]
-
   # The actions the workflows themselves pin. These go stale silently: a
   # deprecated runner image, or a Node version dropped from an action, is only
   # noticed when a job starts warning, or fails.

.github/labeler.yml

@@ -15,7 +15,7 @@
 #   viewer         the JavaScript and CSS that ship inside the HTML report
 #   tests          the test suites
 #   benchmarks     the Python benchmark harnesses and the numbers they produce
-#   documentation  the MkDocs site, the README, the changelog, the figures
+#   documentation  the website and docs, the README, the changelog, the figures
 #   packaging      what a release is made of: crate metadata, lockfile, licence
 #   ci             everything under .github, plus the repository's own scripts
 #
@@ -118,10 +118,8 @@ documentation:
       - any-glob-to-any-file:
           - "docs/**"
           - "assets/**"
-          - "mkdocs.yml"
           - "README.md"
           - "CHANGELOG.md"
-          - "requirements-docs.txt"
 
 # No CITATION.cff and no archived record to keep in step with either, so unlike
 # other repositories in the lab there is nothing else to list here. The lockfile

.github/pull_request_template.md

@@ -41,5 +41,5 @@ here iterates the whole matrix rather than the visible window.
 - [ ] `RECORE_REQUIRE_MINIMAP2=1 cargo test --locked --all-targets` passes. <!-- The variable turns the "minimap2 not in PATH" skip into a failure, so a green run means the end-to-end test actually ran. If you do not have minimap2 locally, say so and let CI be the check. -->
 - [ ] New behaviour has a test, or I have said above why it does not.
 - [ ] `CHANGELOG.md` has an entry under `## [Unreleased]`, if a user would notice this.
-- [ ] Documentation under `docs/` is updated if the change is user-visible, and `mkdocs build --strict` passes.
+- [ ] Documentation under `docs/` is updated if the change is user-visible, and `python3 tools/check_site.py --recore target/debug/recore --run-tutorial` passes.
 - [ ] If I touched the report: it still loads nothing from the network, it still draws only the visible window, and I regenerated `docs/assets/example-report.html` if the viewer changed.

.github/workflows/dependabot-auto-merge.yml

@@ -119,18 +119,18 @@ jobs:
       #   CI / Build, test, clippy, fmt
       #                          rustfmt, clippy -D warnings, and the test suite
       #                          with the end-to-end run made mandatory.
-      #   Documentation / Build  mkdocs build --strict.
+      #   Documentation / Build  tools/check_site.py: the website against the code.
       #
-      # The docs workflow is filtered by path, so on most of these pull requests
-      # it never runs and never appears in the list. An absent check is read as
+      # The docs workflow is filtered by path, so on some of these pull requests
+      # (an action bump) it never runs and never appears in the list. An absent check is read as
       # satisfied, not as pending, because the alternative is a cargo bump
       # sitting here until the timeout waiting for a job that was never going to
       # start. Reading it that way is safe because both workflows hang off the
       # same pull_request event: by the time CI has finished, minutes later,
       # a docs run that was ever going to happen has long since registered
       # itself as queued. And it does happen on the pull requests where it
-      # matters, since requirements-docs.txt and docs.yml are both in that
-      # workflow's path filter.
+      # matters, since Cargo.lock and docs.yml are both in that workflow's path
+      # filter.
       #
       # If the same check ever shows up twice for one commit, both copies are
       # read: pending if either is pending, green only if every one is green.

.github/workflows/dependency-review.yml

@@ -11,7 +11,7 @@ name: Dependency review
 # already in the tree is somebody else's conversation, and Dependabot is the one
 # having it.
 #
-# What it can see here is Cargo.lock and requirements-docs.txt. The lockfile is
+# What it can see here is Cargo.lock. The lockfile is
 # committed, so the comparison is against the exact transitive versions the
 # build actually uses rather than whatever the ranges in Cargo.toml would
 # resolve to today. There is deliberately no package.json to review: the report

.github/workflows/docs.yml

@@ -1,85 +1,66 @@
 name: Documentation
 
-# Build the MkDocs Material site and publish it to GitHub Pages (gh-pages branch).
-# After the first successful run, set Settings -> Pages -> Source to "Deploy from
-# a branch" and pick the gh-pages branch (root).
+# Checks the website in docs/ against the code it describes.
 #
-# Deploys on a push to main, so the published site tracks main and does not
-# redeploy on every push to a working branch. To publish on demand from any
-# branch, use the "Run workflow" button (workflow_dispatch).
+# The site is plain HTML with no build step (docs/index.html, reference.html and
+# assets/), so there is nothing to build or deploy: GitHub Pages can serve the
+# folder as it is, with Settings -> Pages -> "Deploy from a branch" -> main ->
+# /docs, once the repository is public or the organisation is on a paid plan.
+# What can still go wrong is drift, and tools/check_site.py fails on it: a dead
+# link or anchor, an option the pages show that `recore --help` does not have,
+# an option or a default the reference gets wrong, and an example run whose
+# counts are not the ones the page promises. That last part runs the "Try it"
+# commands for real, which is why this needs minimap2 and a build.
+#
+# The workflow and job names are what the Dependabot auto-merge gate waits for
+# ("Documentation" / "Build"); tools/check_automerge_gate.py fails CI if they
+# drift apart.
 
 on:
   push:
     branches:
       - main
     paths:
       - "docs/**"
-      - "mkdocs.yml"
-      - "CHANGELOG.md"
-      - "requirements-docs.txt"
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "benchmarks/make_tutorial_dataset.py"
+      - "tools/check_site.py"
       - ".github/workflows/docs.yml"
   pull_request:
     paths:
       - "docs/**"
-      - "mkdocs.yml"
-      - "CHANGELOG.md"
-      - "requirements-docs.txt"
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "benchmarks/make_tutorial_dataset.py"
+      - "tools/check_site.py"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
   group: docs-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  CARGO_TERM_COLOR: always
+
 jobs:
   build:
     name: Build
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v7
-
-      - uses: actions/setup-python@v7
-        with:
-          python-version: "3.x"
-
-      - name: Install dependencies
-        run: pip install -r requirements-docs.txt
-
-      # --strict turns broken internal links and missing nav entries into
-      # errors, so a pull request that breaks one fails here instead of
-      # shipping a dead link.
-      - name: Build
-        run: mkdocs build --strict
-
-  deploy:
-    name: Deploy
-    needs: build
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v7
-        with:
-          python-version: "3.x"
-
-      - name: Cache MkDocs build
-        uses: actions/cache@v6
-        with:
-          key: mkdocs-material-${{ github.sha }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-
-      - name: Install dependencies
-        run: pip install -r requirements-docs.txt
-
-      - name: Build and deploy
-        run: mkdocs gh-deploy --force --strict
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Install minimap2
+        run: sudo apt-get update && sudo apt-get install -y minimap2
+      - name: Build recore
+        run: cargo build --locked
+      - name: The website matches the code
+        run: python3 tools/check_site.py --recore target/debug/recore --run-tutorial

.gitignore

@@ -14,7 +14,7 @@ __pycache__/
 .DS_Store
 Thumbs.db
 
-# Docs site (mkdocs build output)
+# Output of the MkDocs site this repository used to build
 /site/
 /.cache/
 

CHANGELOG.md

@@ -88,6 +88,18 @@ and Recore uses semantic versioning.
 
 ### Changed
 
+- The documentation site is now a short website instead of fourteen MkDocs
+  pages: an install line, a command builder that writes the run for your
+  pangenome tool and the files you have, a one-minute example with the counts it
+  should give, the example report to click through, the one setting that
+  matters, and the first questions people ask. A reference page lists every
+  option, output file, cell state and rescue type, with a filter. It is plain
+  HTML in `docs/` with no build step, so it opens from a clone and GitHub Pages
+  can serve the folder as it is. `tools/check_site.py` runs in CI and fails if a
+  link or anchor is dead, if the site shows an option `recore --help` does not
+  have, if the reference misses an option or gets a default wrong, or if the
+  example run no longer gives the counts the page promises. The long-form pages
+  stay as markdown, rendered on GitHub, and MkDocs is gone from the repository.
 - `publication_status` in `orthology_evidence.tsv` follows `matrix_action`.
   Evidence the matrix policy or a quality floor kept out reads `held_out_policy`
   or `held_out_quality` instead of a `corrected...` value, and a strict

README.md

@@ -7,7 +7,7 @@
 **Post-hoc rescue, audit, and quality control of pangenome presence/absence matrices.**
 **Pure Rust · one external dependency · Linux and macOS**
 
-[Documentation](docs/) · [Install](#installation) · [Quick start](#quick-start) · [Tutorial](docs/getting-started/tutorial.md) · [Citation](#citation)
+[Documentation](#documentation) · [Install](#installation) · [Quick start](#quick-start) · [Tutorial](docs/getting-started/tutorial.md) · [Citation](#citation)
 
 <a href="https://github.com/PathoGenOmics-Lab/recore/actions/workflows/ci.yml"><img src="https://github.com/PathoGenOmics-Lab/recore/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3-blue.svg" alt="License: GPLv3"></a>
@@ -47,15 +47,15 @@ Needs [Rust 1.85+](https://www.rust-lang.org/tools/install) to build and
 [minimap2](https://github.com/lh3/minimap2) on `PATH` to run.
 
 ```bash
-git clone https://github.com/PathoGenOmics-Lab/recore.git
-cd recore
-cargo build --release        # binary at target/release/recore
+conda install -c bioconda minimap2     # or: brew install minimap2 / sudo apt install minimap2
+cargo install --git https://github.com/PathoGenOmics-Lab/recore --locked
+recore --version
 ```
 
-Tagged releases also ship Linux and macOS binaries on the
-[Releases](https://github.com/PathoGenOmics-Lab/recore/releases) page.
-[Installation](docs/getting-started/installation.md) covers conda, MMseqs2 and
-checking the install.
+Or build a clone with `cargo build --release` (the binary lands at
+`target/release/recore`). `--nsc-engine mmseqs2` also needs
+[MMseqs2](https://github.com/soedinglab/MMseqs2) on `PATH`; the default engine
+is built in.
 
 ## Quick start
 
@@ -95,13 +95,20 @@ with eleven false absences planted in it and walks through the run.
 
 ## Documentation
 
-Every page is a markdown file in this repository and reads here on GitHub.
+The quickest way in is the website in [`docs/`](docs/index.html): an install
+line, a command builder for your pangenome tool, a one-minute example, the
+example report to click through, and one reference page with every option,
+output file and cell state. It is plain HTML with no build step, so open
+`docs/index.html` from a clone; once the repository is public, GitHub Pages can
+serve it straight from `main` and `/docs`. `tools/check_site.py` keeps it
+honest in CI: every option it shows exists, the defaults match `recore --help`,
+and the example run gives the numbers the page promises.
+
+The long versions are markdown files in this repository and read here on GitHub.
 
 | Start here | |
 |---|---|
 | [Tutorial](docs/getting-started/tutorial.md) | a full run on a generated dataset with known answers |
-| [Installation](docs/getting-started/installation.md) | requirements, from source, pre-built binaries |
-| [Quick start](docs/getting-started/quickstart.md) | the run most people want, and what to read first |
 | [Inputs](docs/getting-started/inputs.md) | what each input is, and how the names have to match |
 
 | Reference | |
@@ -122,13 +129,6 @@ Every page is a markdown file in this repository and reads here on GitHub.
 Version history is in [CHANGELOG.md](CHANGELOG.md). Benchmark design and
 reproduction is in [benchmarks/README.md](benchmarks/README.md).
 
-> [!NOTE]
-> The same pages build into a searchable site with an example report you can
-> open (`pip install -r requirements-docs.txt && mkdocs serve`). It is deployed
-> to `gh-pages` on every push to `main`, but GitHub Pages needs the repository
-> to be public, or the organisation to be on a paid plan, so
-> <https://pathogenomics-lab.github.io/recore/> is not served yet.
-
 If the documentation does not answer it, ask in
 [Discussions](https://github.com/PathoGenOmics-Lab/recore/discussions). Issues
 are for something that crashed, refused to run, or is plainly wrong.