docs: a Docs tab, light code boxes, and an illustrated How it works page

.github/CONTRIBUTING.md

@@ -235,13 +235,19 @@ you anything tends not to get run.
 
 ## Documentation
 
-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.
+The website is plain HTML in `docs/` (`index.html`, `how-it-works.html`,
+`reference.html` and `assets/`): open `docs/index.html` to see a change. The
+drawings of How it works (`assets/how.js`) decide with a copy of
+`evidence_state` and `matrix_policy_corrects` from `src/pipeline.rs`; change
+them together. The Docs tab is the markdown under `docs/`, turned into pages by
+`tools/build_docs.py`; after editing a `.md` file, run it and commit what it
+writes. The documentation workflow runs `tools/check_site.py`, which fails on a
+documentation page that no longer matches its markdown, 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, a walkthrough that decides
+differently from the code, or an example run whose counts differ from the
+page's, instead of a stale page somebody finds six months later. The markdown
+also reads on GitHub as it is.
 
 `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/workflows/docs.yml

@@ -2,15 +2,18 @@ name: Documentation
 
 # Checks the website in docs/ against the code it describes.
 #
-# 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 site is plain HTML with no build step (docs/index.html, how-it-works.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. The Docs tab is built from the markdown by tools/build_docs.py
+# and committed. What can still go wrong is drift, and tools/check_site.py fails
+# on it: a documentation page that no longer matches its markdown, 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, a walkthrough that decides
+# differently from src/pipeline.rs, 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
@@ -27,6 +30,7 @@ on:
       - "Cargo.lock"
       - "benchmarks/make_tutorial_dataset.py"
       - "tools/check_site.py"
+      - "tools/build_docs.py"
       - ".github/workflows/docs.yml"
   pull_request:
     paths:
@@ -36,6 +40,7 @@ on:
       - "Cargo.lock"
       - "benchmarks/make_tutorial_dataset.py"
       - "tools/check_site.py"
+      - "tools/build_docs.py"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 

CHANGELOG.md

@@ -104,6 +104,15 @@ and Recore uses semantic versioning.
   embedded report follows; pointing at a cell of the opening matrix says what
   happened to it; the policy section shows which of ten found genes each policy
   puts back; and GitHub is a button in the header, the opening and the end.
+  A Docs tab carries every long page in the site's design, with a page list,
+  contents that follow the reading, previous and next links, a search box over
+  all of them and an edit link to GitHub; `tools/build_docs.py` builds the pages
+  from the markdown, which stays the source and still reads on GitHub. Code
+  boxes are light in the light theme. A How it works page follows one empty
+  cell through seven animated drawings, from the search to what gets written
+  down: pick what the search finds, whether the neighbours agree and the
+  policy, and the drawings decide by the same rules as the code, which
+  `tools/check_site.py` holds them to.
 - `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

@@ -97,14 +97,17 @@ with eleven false absences planted in it and walks through the run.
 
 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.
+example report to click through, an illustrated walk through how one empty cell
+is decided, a reference page with every option, output file and cell state, and
+a Docs tab with every page below, searchable. 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`. The Docs pages are
+built from the markdown by `tools/build_docs.py`, and `tools/check_site.py`
+keeps the site honest in CI: the pages match their markdown, every option it
+shows exists, the defaults match `recore --help`, the walkthrough decides by
+the code's rules, and the example run gives the numbers the page promises.
+
+The same pages are markdown files in this repository and read here on GitHub.
 
 | Start here | |
 |---|---|

docs/about/citation.html

@@ -0,0 +1,125 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Citation | Recore docs</title>
+<meta name="description" content="How to cite Recore.">
+<link rel="icon" href="../assets/recore_logo.svg" type="image/svg+xml">
+<link rel="stylesheet" href="../assets/site.css">
+<script>try { document.documentElement.dataset.theme = localStorage.getItem("recore.theme") === "light" ? "light" : "dark"; } catch (e) { document.documentElement.dataset.theme = "dark"; }</script>
+</head>
+<body>
+<a class="skip" href="#content">Skip to the content</a>
+<!-- Generated by tools/build_docs.py from the markdown next to this file. Edit that, then run it. -->
+<header class="top">
+  <div class="wrap">
+    <a class="brand" href="../index.html" aria-label="Recore home">
+      <img class="logo-light" src="../assets/recore_logo.svg" alt="Recore" width="74" height="34">
+      <img class="logo-dark" src="../assets/recore_logo_dark.svg" alt="Recore" width="74" height="34">
+    </a>
+    <nav class="nav" aria-label="Site">
+      <a class="nav-wide" href="../index.html#start">Install</a>
+      <a class="nav-wide" href="../index.html#command">Your command</a>
+      <a class="nav-wide" href="../index.html#try">Try it</a>
+      <a class="nav-optional" href="../how-it-works.html">How it works</a>
+      <a href="../documentation.html" aria-current="page">Docs</a>
+      <a class="nav-optional" href="../reference.html">Reference</a>
+      <a class="gh-link" href="https://github.com/PathoGenOmics-Lab/recore"><svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg><span>GitHub</span></a>
+      <button class="icon-btn" type="button" data-theme-toggle aria-label="Switch between light and dark">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="4.5"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
+      </button>
+    </nav>
+  </div>
+</header>
+<div class="wrap docs-layout">
+<aside class="docs-nav" aria-label="Documentation">
+  <div class="docs-search">
+    <input type="search" placeholder="Search the docs" aria-label="Search the documentation" data-docs-search>
+    <div class="docs-results" data-docs-results hidden></div>
+  </div>
+  <details class="docs-menu" open>
+    <summary>Pages</summary>
+    <p class="docs-section">Getting started</p>
+    <ul>
+      <li><a href="../getting-started/tutorial.html">Tutorial</a></li>
+      <li><a href="../getting-started/inputs.html">Inputs</a></li>
+    </ul>
+    <p class="docs-section">Guide</p>
+    <ul>
+      <li><a href="../guide/parameters.html">Parameters</a></li>
+      <li><a href="../guide/matrix-policies.html">Matrix policies</a></li>
+      <li><a href="../guide/outputs.html">Output files</a></li>
+      <li><a href="../guide/report.html">The report</a></li>
+    </ul>
+    <p class="docs-section">How it works</p>
+    <ul>
+      <li><a href="../how-it-works.html">Step by step, illustrated</a></li>
+      <li><a href="../how-it-works/algorithm.html">Algorithm</a></li>
+      <li><a href="../how-it-works/evidence-states.html">Evidence states</a></li>
+      <li><a href="../how-it-works/rescue-types.html">Rescue types</a></li>
+      <li><a href="../how-it-works/evolutionary-events.html">Evolutionary events</a></li>
+      <li><a href="../how-it-works/limits.html">Limits and speed</a></li>
+    </ul>
+    <p class="docs-section">About</p>
+    <ul>
+      <li><a href="../about/citation.html" aria-current="page">Citation</a></li>
+      <li><a href="../about/contributing.html">Contributing</a></li>
+    </ul>
+  </details>
+</aside>
+<main class="prose" id="content">
+<p class="crumb"><a href="../documentation.html">Docs</a> / About</p>
+<h1 id="citation">Citation</h1>
+<p>If you use Recore, please cite:</p>
+<blockquote><p>Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. <em>In preparation.</em></p></blockquote>
+<div class="code" data-lang="bibtex"><pre>@misc{recore,
+  author       = {Ruiz-Rodriguez, Paula and others},
+  title        = {Recore: post-hoc rescue and quality control of pangenome
+                  presence/absence matrices},
+  year         = {2026},
+  note         = {In preparation},
+  howpublished = {\url{https://github.com/PathoGenOmics-Lab/recore}}
+}</pre></div>
+<p>Please also cite the tools Recore depends on for the run you report:</p>
+<ul><li><strong>minimap2</strong>, for every sequence search: Li H. (2018). Minimap2: pairwise alignment for nucleotide sequences. <em>Bioinformatics</em> 34(18):3094-3100.</li><li><strong>MMseqs2</strong>, if you used <code>--nsc-engine mmseqs2</code>: Steinegger M, Soeding J. (2017). MMseqs2 enables sensitive protein sequence searching for the analysis of massive data sets. <em>Nature Biotechnology</em> 35:1026-1028.</li><li>the pangenome tool that produced the input matrix, for example <strong>Panaroo</strong>: Tonkin-Hill G, et al. (2020). Producing polished prokaryotic pangenomes with the Panaroo pipeline. <em>Genome Biology</em> 21:180.</li></ul>
+<h2 id="contact">Contact<a class="anchor" href="#contact" aria-label="Link to this section">#</a></h2>
+<p>Paula Ruiz-Rodriguez, paula.ruiz.rodriguez@csic.es</p>
+<p>PathoGenOmics Lab, <a href="https://github.com/PathoGenOmics-Lab">github.com/PathoGenOmics-Lab</a></p>
+<h2 id="license">License<a class="anchor" href="#license" aria-label="Link to this section">#</a></h2>
+<p>GNU General Public License v3.0. See <a href="https://github.com/PathoGenOmics-Lab/recore/blob/main/LICENSE">LICENSE</a>.</p>
+<p class="edit"><a href="https://github.com/PathoGenOmics-Lab/recore/blob/main/docs/about/citation.md"><svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>Edit this page on GitHub</a></p>
+<nav class="pager" aria-label="Previous and next page"><a class="prev" href="../how-it-works/limits.html"><span>Previous</span>Limits and speed</a><a class="next" href="../about/contributing.html"><span>Next</span>Contributing</a></nav>
+</main>
+<aside class="docs-toc" aria-label="On this page"><p>On this page</p><ul><li class="toc-2"><a href="#contact">Contact</a></li><li class="toc-2"><a href="#license">License</a></li></ul></aside>
+</div>
+<footer class="foot">
+  <div class="wrap">
+    <div>
+      <h3>Cite</h3>
+      <blockquote>Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. <i>In preparation.</i></blockquote>
+    </div>
+    <div>
+      <h3>Learn more</h3>
+      <ul>
+        <li><a href="../index.html">Get started</a></li>
+        <li><a href="../documentation.html">Documentation</a></li>
+        <li><a href="../reference.html">Reference: options, files, states</a></li>
+        <li><a href="https://github.com/PathoGenOmics-Lab/recore/blob/main/CHANGELOG.md">Changelog</a></li>
+      </ul>
+    </div>
+    <div>
+      <h3>Project</h3>
+      <ul>
+        <li><a href="https://github.com/PathoGenOmics-Lab/recore">GitHub</a></li>
+        <li><a href="https://github.com/PathoGenOmics-Lab/recore/discussions">Questions</a></li>
+        <li><a href="https://github.com/PathoGenOmics-Lab/recore/issues">Report a bug</a></li>
+        <li>GPL-3.0 &middot; PathoGenOmics Lab</li>
+      </ul>
+    </div>
+  </div>
+</footer>
+<script src="../assets/search-index.js"></script>
+<script src="../assets/site.js"></script>
+</body>
+</html>