Design: the writer, and what every page shows

Design: the writer, and what every page shows#

Note

A design document, written 2026-10-14 as the second of the four steps the maintainer approved: vocabulary (Vocabulary), then this inventory, then the Sphinx writer, then the documentation site. Status: built (2026-10-15). The writer renders every page from the index and the files it names, the build calls it (sitefiles.write_site()), and the generator is gone. The decisions it proposes are marked proposed until the maintainer takes them.

What this is for#

A writer turns the index into pages for one site tool. For the Sphinx writer to replace the generator that writes pages today, two things have to be true: the index must carry every fact a page shows, and every rendering a page shows must be something the writer can make from facts. This page inventories every section of every page the generator writes now, says which it is, and lists what the index must gain. The rule it applies is the one on the vocabulary page: the index records facts about the build, including comparisons it made, and no renderings.

The writer’s input: the index, and the files it names#

Proposed. The vocabulary page settles that the writer reads the write-ups the index points at, because they are source and not facts about the build. The inventory below shows the same is true of two more things a page shows: the first rows of a dataframe (the glimpse) and a chart’s HTML (the iframe). Neither is a fact about the build, and neither belongs in a JSON file; both are files the index names, with their hashes. So the writer’s input is: the index, and the files the index names — write-ups, data files, chart files, notebooks — read at the paths the index gives, and nothing else. A writer never reads a manifest, never walks a folder, and never asks git. The index is the map; the files are the territory it maps.

The inventory#

Each row: a section a page shows today; what it shows; whether that is a fact (belongs in the index), a rendering (the writer makes it from facts), or a file (the writer reads what the index names); where the generator gets it today; and whether the index has it.

Every asset page#

Section	Shows	Is	Today from	In the index
Title	Kind, ID, name	fact	manifest	yes
Freshness line	When the data file was last written (“Data updated 2 days ago”); for a chart, when the chart file was; “Code updated” on the pipeline page	fact: a file’s modification time; a pipeline’s last code change	file system; git	no. Add `modified_at` to a `file` location; add the pipeline’s last code change to the `Pipeline` record
The write-up	The author’s text, from `docs_path` or inline `docs`	file	the file, or the manifest	partly: `docs` has the path or the text. Add the hash (decided)
Provenance panel	What this is, where, hash, size, rows, built by, made from, used by, version	fact	the index	yes (6b)
Manifest tables	Name, description, tags, sources, providers, links, access, pull method, units, frequency… every declared field	fact	manifest	yes: every declared field is on the record
Pipeline manifest table	Name, ID, maintainer, contributors, repository, site URL, OS, code update date, linked dataframes, build command	fact	manifest; git	mostly. Add `site_url` and `readme` if absent; the code change date as above; linked dataframes are the `assets` list
Download links	Parquet, Excel, HTML of the chart	rendering of a location	manifest	yes (location)

Dataframe page#

Section	Shows	Is	Today from	In the index
Glimpse	Row and column counts, dtypes, one sample row	counts and dtypes: fact (`row_count`, `columns`); the sample row: file	the parquet file	counts and columns yes; the sample is read from the file the location names
Data available up to (min/max)	For a file: the least and the greatest, over the other columns, of the last date at which that column is non-null (a staleness measure across columns); for a table or query: the first and last date	a comparison the writer makes from the file, for a file; a fact, for a table or query	the parquet file; the engine	the plain first and last date are now a fact, `date_range`, for both; the per-column measure the file page shows stays a rendering the writer computes from the file it names
Table / query row	Source, identifier or SQL	fact	manifest	yes (location)
Linked charts	Charts whose `dataframe` is this one	rendering of a comparison	manifest	yes: the charts’ `inputs`; the panel’s reverse map
Series tables	Documented columns	fact	manifest	yes (`Series` records)

Chart page#

Section	Shows	Is	Today from	In the index
Front matter	Date, tags, category, for ABlog’s listing	rendering of facts: the chart file’s time, the dataframe’s `sources`, the chart’s `tags`	manifest; file system	yes once `modified_at` exists
The chart	The HTML file, in an iframe; “Sources: …” under it	file; a fact	the chart file; the dataframe’s declared fields	the location names the file; `sources` is on the dataframe record
Chart specs	Frequency, units, period, release lag…	fact	manifest	yes

Model page#

Section	Shows	Is	Today from	In the index
Scores	The metrics file’s values	fact	the metrics file	yes (`metrics`)
Versions table	Each version: name, made, commit, labels, each metric	fact	the store	yes (`versions`)
Trained on	Each input, linked where the site has it	rendering: links from `inputs`	manifest; site manifest	yes (`inputs`)
Out of date	The inputs that moved, then and now	fact: a comparison the build made	the store, the lockfile, the files	yes (`trained_with`, `stale_inputs`)
Files	A directory model’s files and sizes	fact	the file system	yes (`files`)

Pipeline page, notebooks, notes#

Page	Shows	Is	Today from	In the index
Pipeline README	The README’s text under a title; the manifest table	file; facts	the README file	`docs` on the `Pipeline` record names it; add the hash
Notebook	The executed notebook, rendered by Sphinx	file	the `.ipynb` file	the location names it
Note	The write-up	file	the file	the location names it

The catalog’s own pages#

Page	Shows	Is	Today from	In the index
Landing	Cards to charts, dataframes, models, pipelines, contributing, diagnostics	rendering (static text)	the theme	nothing needed
Lists (dataframes, models, pipelines)	Every page of a kind	rendering of the records	the manifest	yes
Charts	ABlog’s listing by date and category	rendering	front matter	yes once `modified_at` exists
Diagnostics	Which assets lack which required fields, against the policy	a comparison: rendering, or a fact the build records	`diagnostics.py`, against `[policy]`	the `Catalog` record must carry the policy; then the writer computes it, or the build records a `complete` flag per record. Proposed: the writer computes it; the policy is a fact, completeness is a comparison any reader can make
Contributing	Static text	rendering	the theme	nothing needed

What the index must gain#

In the order a writer needs them. Each is a fact, and each is small. (All built 2026-10-14, the same day, as 6c; tests/test_index.py, TestWhatTheWriterNeeds. The diff reads what a file holds, not when it was written, so modified_at alone is not a change; a changed write-up reads “write-up changed”, a date_range whose last date moved “data reaches further” or “less far”, a pipeline’s code_changed_at “source changed”. A review found and fixed: code_changed_at was written from file times by any build_index() while the schema promised git — it is present only in an index a docs build writes; a directory’s modified_at was the directory’s own; a text date_col gave a lexical range — only temporal columns are read, in ISO 8601; the diff said “reaches further” whatever the direction. Known: the time is carried as an instant when freshly worked out, and from the incremental state’s local-time string when remembered, so a state file reused on a machine in another zone, or a stamp in the repeated hour of a DST change, can be off.)

The write-up’s path and hash on every asset record and on the Pipeline record (its README). Decided 2026-10-14. A build then says which text it showed, and a diff says the write-up changed.
modified_at on every file location: when the file was last written, in UTC. The freshness lines and ABlog’s dates come from it. Proposed.
date_range on a dataframe record with a date_col: the first and last date in the data, in ISO 8601; a text column is parsed as dates, and what does not parse is left out. Proposed. The engine answers it for a table or a query; for a file it is one column, read from the parquet statistics. The file page’s per-column “available up to” rows are a different quantity, a comparison across columns, which the writer computes from the file it names.
code_changed_at on the Pipeline record: when the pipeline’s code last changed, as the build works it out (the last commit that touched the source where it is committed and unmodified, else the newest modification time), which the pipeline page shows today. Proposed. The index asks git for nothing itself: the build works the times out once, and an incremental build remembers them for the pipelines it reuses. It is the first field of the Build record the index design leaves for later; the rest of that record (the commit the site was built at, the time, the tool versions) belongs with it, and the envelope’s generator already carries the versions.
The policy on the Catalog record, so the diagnostics page is a comparison a reader can make. Proposed. The schema has a place for it.
site_url and readme on the Pipeline record if either is missing; a check, not a design.

Nothing on this list is a rendering. The sample row, the chart HTML and the write-up text stay in the files the index names.

The writer, in outline#

Proposed.

One module per site tool: chartbook/writers/sphinx.py first. Its input is the index and the files it names; its output is a folder of pages and the files Sphinx needs beside them. It takes the theme (pipeline or catalog) and the build options the pages depend on.
The link scheme is the writer’s. page_path(record) -> str, pipeline_page_link(record) and link_to_dataframe(record, from_kind), one rule per writer. The provenance panel names assets by ID today because the scheme is not yet a function; it becomes one here, and the panel gains links.
Today’s Jinja templates become the Sphinx writer’s templates. They already render from a context; the context becomes the record plus what the writer computed. The generator is replaced section by section, each section’s page compared with the old one on the example sites, and the old code removed when the pages match.
Golden tests: one page of each kind, rendered from a fixed index and fixed files, compared whole. The index is small enough to keep as a fixture.
MkDocs and Next.js are later writers reading the same index; they are why the index stays free of renderings. MkDocs is built (below); Next.js is not scheduled.

A second writer: MkDocs#

Proposed 2026-10-16. The maintainer asked for an MkDocs writer, behind an extra: pip install chartbook keeps installing Sphinx, and pip install chartbook[mkdocs] adds MkDocs. The writer is the proof that the index is what it claims to be: a second site tool, reading the same index, writing pages of its own, with the build unchanged above the writer.

Which tool a site is built with is a fact about the pipeline’s site, so it is in the manifest: [project] writer = "mkdocs", default "sphinx". A catalog’s choice applies to the catalog’s site; a pipeline’s to its own. (chartbook docs keeps no flag for it: the site is built the same way by everyone who builds it.)

What the writer is. chartbook/writers/mkdocs.py, MkDocsWriter, with the Sphinx writer’s methods and signatures: page_path(record), page(record), pipeline_page_link, link_to_dataframe, catalog_page_paths(), catalog_page(path). Its input rule is the same: the index and the files it names, nothing else. Its output is a MkDocs project: mkdocs.yml with the nav written from the index, and a docs/ folder of Markdown pages in MkDocs’ dialect (Material admonitions, plain tables, relative .md links). The provenance and manifest templates are plain Markdown already and are shared; the two templates that use MyST (chart_entry_top.md, freshness.md) and the theme’s own pages (index.md, charts.md, the catalog’s five) get MkDocs versions in a theme folder of the writer’s own.

What MkDocs does not have. Sphinx’s blog (ablog) carries the notes; in MkDocs the notes are pages listed on the front page, newest first, with their dates. Notebooks are rendered by mkdocs-jupyter, which the extra installs. Charts are HTML files, shown as they are now, in an iframe on the chart page. The diagnostics page, the catalog’s tables and the search are MkDocs’ own.

The build. sitefiles.write_site() picks the writer by the manifest and writes the pages; build_docs runs mkdocs build where it runs sphinx-build, and copies the site out the same way; index.json is written beside the site as now, by code that never knew which tool rendered it. The incremental build is Sphinx’s for now: an MkDocs site is built whole.

Tests. The golden tests of tests/test_writer_sphinx.py have an MkDocs twin: one page of each kind from the same fixed index, compared whole. A build test runs mkdocs build where MkDocs is installed (the test environments install it) and checks the pages are there and the index is beside them. The first page compared by eye is the example pipelines’ sites, built with both writers.

Not in this step. Theme options beyond the logo and the favicon the manifest already has; a Next.js writer; a plugin seam for writers (two implementations are not three).

Found on the way, 2026-10-16: three links the Sphinx writer carries from the generator do not resolve, in either site tool: the dataframe page’s link to itself in the pipeline theme (../dataframes/<slug>/<name>.md from cb/dataframes/<slug>/), the chart page’s link to itself (../../charts/<slug>.<name>.md from cb/charts/) and, in the catalog theme, a dataframe page’s link to its pipeline (../pipelines/<slug>_README.md from cb/dataframes/<slug>/), and in the catalog theme a dataframe page’s link to itself (<slug>/<name>.md from cb/dataframes/<slug>/); Sphinx renders each as an anchor on the same page. MkDocs reports them as warnings. They are the link scheme’s to fix, for both writers at once, with the golden tests updated; not part of this step. Fixed 2026-10-16: link_to_dataframe and pipeline_page_link are relative to the page they are on, the linked-charts list uses the page’s own prefix, and the MkDocs build test asserts that MkDocs reports no unresolved link.

Built 2026-10-16: chartbook.writers.mkdocs.MkDocsWriter, a subclass of the Sphinx writer that swaps the template search path for a theme folder of its own (chartbook/docs_src_mkdocs/<theme>) and renders the front pages and lists as links rather than toctrees; [project] writer = "mkdocs" chooses it, and the build (build_docs._generate_docs_mkdocs) writes the pages under pages/, mkdocs.yml beside them with the navigation from the records, and runs mkdocs build. The site’s own pages (cb/charts.md, the catalog’s) are a question the build asks any writer, own_page_paths() and own_page(); the Sphinx writer answers with the catalog’s pages, the MkDocs writer with the chart listing too. The incremental build is Sphinx’s and says so when asked for an MkDocs site. pip install chartbook[mkdocs] installs MkDocs, the Material theme and mkdocs-jupyter; pip install chartbook still installs Sphinx and nothing of MkDocs. Two things the proposal above says differently from what was built: the notes and the charts are listed by name, not newest first; and the tests are not golden twins but checks that every page of a pipeline site and a catalog site is free of Sphinx syntax, that the chart listing and the navigation name every page, and that MkDocs builds a pipeline site (notes, site pages in the order of index_toc.md, MkDocs’ own search) and a catalog site end to end. A pipeline’s own site pages are copied as they are, listed on the front page and in the navigation, and one that carries a MyST fence is named in a warning, since MkDocs shows it as code. chartbook catalog build reads the catalog’s manifest and builds whole when it names MkDocs; --watch is refused there. The model page’s versions table, which had blank lines between its rows and so rendered as paragraphs in both tools, is a table now.

As built, slice by slice#

2026-10-15, slice 1: the dataframe page. chartbook/writers/sphinx.py, SphinxWriter. Its input is the full index (with resolved_path, since it reads the files the index names) and the files; it takes the theme, the project’s own docs_src for template overrides, and the two build options the page depends on. It renders today’s templates unchanged, from a context made of records: the dataframe’s declared fields and location; a project table and the dataframes list made from the Pipeline record; the write-up read at the path the record gives; the glimpse and the per-column date rows from the data file, or from the engine for a table or a query, opened through chartbook.backends.source_url() from the public url the location now carries; the freshness line from modified_at; the panel from the records. The link scheme is three functions on the writer. A golden test (tests/test_writer_sphinx.py) builds the site with the generator and asserts the writer’s page is the same text, on a file-backed pipeline and on one with a DuckDB table and query. Two facts were added for it: site_url on the Pipeline record (dropped from the published index when it is a local file:// path, as resolved_path is) and url on a table or query location. Not yet: the chart, model, notebook, note and pipeline pages, the catalog’s list pages, and the build calling the writer instead of the generator.

Decided with the slice, proposed: a write-up is text, not a template. The generator had concatenated the write-up into the page’s Jinja source, so {{ name }} or {% if %} inside a write-up was evaluated, and {{'a': 1}} crashed the build; nothing documented it and no example used it. The writer passes the write-up as a value, and the generator’s dataframe page does the same now, so what the author wrote is what the page shows. The date rows of a table or query come from the index’s date_range, which parses a text column as dates, where the generator had shown the engine’s least and greatest text. A declared path is shown normalized (../shared/x as the folder it names), as the index and the resolver have it. An adversarial review of the slice found the writer resolving a relative DuckDB url against the process’s working directory instead of the pipeline’s folder, which the golden test’s chdir had hidden (fixed; the catalog theme, built from the catalog’s root, is tested now); a published index gave a bare KeyError (a message says the writer needs the full index); docs_src_dir unset dropped the override paths (it defaults as the generator’s). Known: the pipeline table’s code-change time is converted back from UTC to local for the page and can land on the other side of a repeated DST hour.

2026-10-15, slice 2: the chart page. SphinxWriter.chart_page(). The chart’s record gives its declared fields and its file’s path and modified_at; its inputs name the dataframe it was drawn from, whose record gives the dataframe manifest table, the link and “Data updated”; the pipeline’s record gives the pipeline table and the fallback date for the listing’s front matter; the write-up is read at the path the record gives. The chart’s HTML is not read: the page embeds it by its path under the site, and the build copies it there (that copy is the build’s, not the writer’s, as the inventory said). The link scheme gained the chart page’s own forms, which the generator had: a chart links to the pipeline’s page from one folder less deep, and to its dataframe through ../dataframes/ in both themes. Decided with it, proposed: a chart’s write-up is text too, as a dataframe’s became; and “Data updated” on a chart of a table or query is the engine file’s time — the generator had taken the pipeline folder’s own modification time for it, since a table has no path, and now says what the writer says. The writer does not refuse an index that a build could not have made (a chart whose dataframe record is missing, or whose file has no modified_at): it writes the page with no data line and no dataframe table, and takes the listing’s date from the pipeline’s code-change time, as the generator would; the manifest loader and a strict build refuse both cases before an index exists. The golden test covers the chart pages of the file-backed pipeline, of a chart drawn from a DuckDB table (with a series list, which the index had been dropping from charts: series was treated as structural for every kind, where only a dataframe’s become Series records — an adversarial review of the slice found it), and of the catalog. The same review found the generator’s provenance-panel cache keyed by the id() of the records dict, which a later build in the same process could reuse after the first was freed; it holds the records themselves now.

2026-10-15, slice 3: the model page. SphinxWriter.model_page(). The whole page is in the Model record, as the inventory said it should be: scores from metrics, the versions table from versions, the files table from files, “Trained On” from inputs (a link when the input’s record is in this index, which is when its pipeline is part of the site; a name and a note otherwise), and the out-of-date notice from trained_with, inputs_now and stale_inputs. The third of those is new with this slice, and an adversarial review is why: the notice shows each moved input’s hash then and now, and the first version of the writer took “now” from the inputs’ own records (a local dataframe’s content_hash, another pipeline’s pin in pinned_inputs), matching the lockfile-style keys of trained_with (d, rates:treasury) to the build IDs of inputs by name. The review built the cases where that guess is wrong — the declaration reordered after the snapshot, two upstream pipelines with a dataframe of the same name, an input dropped from trained_on but still in the version’s record — and showed the page naming a wrong hash or raising. The index did not state the mapping, so the writer could not derive it; now the record states the three facts of the comparison, keyed alike, and a reader needs nothing else. The model’s bytes are never read. The page’s skeleton is still the generator’s two template strings, imported, until the generator goes and they move here. Decided with it, proposed: a model’s write-up is text too. Aligned on both sides: a directory model’s files are listed by path as text, as the index sorts them (the generator had sorted Path objects, which order a-b/x and a/x the other way); a directory’s modified_at in the index counts the files its hash counts, and is absent when there are none — an empty folder, or one holding only .DS_Store, had been given the folder’s own time and so a “Model updated” line the generator did not show; the generator’s “Data updated” for a dataframe that is a directory now says the same (it had shown the folder’s own modification time, which moves only when an entry is added or removed, so a folder of parts written days ago could be dated today); and training data that a pipeline in the site does not declare is named by its build ID on both sides, with the note “which that pipeline does not declare” (the generator had named it as stated and called it “not part of this site”, which it was). The golden test covers a file model with scores, a bare directory model, one with nothing counted in it, a model with two versions that is out of date on a local and on another pipeline’s dataframe, the same model in a catalog that also holds the other pipeline (where “Trained On” links to it), and one trained on a name its upstream does not declare.

2026-10-15, slice 4: the pipeline page. SphinxWriter.pipeline_page(). In the pipeline theme it is the site’s front page: the theme’s index.md (or the project’s override) rendered with the README’s text from the file the Pipeline record’s docs names, the tables of contents made from the records — notebooks and notes of this pipeline, dataframes and models of the site, each by name — and “Code updated” from code_changed_at. In a catalog it is the pipeline’s README page, cb/pipelines/<slug>_README.md, with the repository and site named above the text from the record’s repo_url and site_url. One fact was added for it: a pipeline’s own site pages. The generator found them by walking [project] site_dir (or docs_src/site/), which the writer may not do; the Pipeline record now carries site_dir (path, and resolved_path until published) and site_pages, every Markdown file under it by relative path, sorted. The build copies them beside the generated pages, as before; the writer lists them in the front page’s table of contents and reads index_toc.md, if it is one of them, to merge in. Decided with it, proposed: notebooks and notes are listed by name, as the index has them, where the generator had kept the manifest’s order; the generator does the same now. Notebooks and notes themselves are files the build copies, not pages the writer renders (the inventory above). The golden test covers a pipeline site with and without its own site pages, one with notes, and a catalog’s README pages. An adversarial review found the generator ordering the site pages as Path objects (guide/intro.md before guide.md) where the index orders them as text, and listing a directory named *.md; the generator now does as the index does, since the index’s order is the one any reader of the JSON reproduces. It also found the writer splitting the README with splitlines(), which breaks on a form feed where the generator’s readlines() does not; both read lines now. A diff says “site pages changed” when one appears or goes. Known: the site pages are listed without hashes, so a diff cannot say which page changed. Proposed: give each the same path + content_hash shape as a write-up when a reader needs it.

2026-10-15, slice 5: the catalog’s own pages. SphinxWriter.catalog_page(path) for index.md, cb/dataframes.md, cb/models.md (when some pipeline declares a model), cb/pipelines.md and cb/diagnostics.md; catalog_page_paths() says which. The landing page and the lists are renderings of the records, as the inventory said; pipelines.md reuses the pipeline manifest table made from each Pipeline record. The diagnostics page is the comparison the inventory proposed the writer should make: each record’s declared fields against the required lists of the policy the Catalog record carries (always resolved, defaults filled). A record carries the fields its entry declared, and its structure stands in for the rest — a location is the path, a docs is the write-up, a chart’s inputs is its dataframe, a model’s inputs are its trained_on — so the rows come out as the generator’s build_diagnostics() does from the manifests, which the golden test holds them to on a catalog with a [policy], a model and assets missing fields. The generator had read the rows back from the CSV the build writes; the build still writes that CSV, and the page links to it. charts.md and contributing.md are static files of the theme that the build copies, not pages the writer renders. One fact was added: the Catalog record’s location, so the writer looks in the catalog’s folder for template overrides as it does in a pipeline’s. Aligned on both sides: the lists and the diagnostics rows are by name (pipelines, then assets), as the index orders records, where the generator had kept the manifests’ order; and an empty “Missing Fields” cell is empty on the page, where the generator’s round trip through pandas had printed nan. An adversarial review found the first version of the comparison treating as missing what a record states in another form: a policy may require readme, site_url or copyright of a pipeline, docs_path, linked_charts, series or source of a dataframe, metrics_path of a model, and the writer had no such keys to look at. Each is put back under the entry’s name now, from the record’s docs, location, the records that point at it (charts, declared series) or its own fields; the Pipeline record carries copyright and the Model record metrics_path for it, as declared. A blank inline write-up (docs = " ") is missing on both sides, since the record’s docs.text is what is checked, not whether a docs exists. The review also found a decision nobody had made: a pipeline that --no-strict leaves out of the build was still listed by the generator’s catalog pages (pages that did not exist) and counted in the diagnostics, while the index, and so the writer, left it out. Decided with the slice, proposed: a skipped pipeline is not part of the site, so the lists and the diagnostics leave it out; the generator does so now. Two more: the loader now refuses a dataframe, chart, notebook or note key that cannot be part of an address, as it already did a model’s, since the index left such an asset out with a warning while the generator rendered its page — the manifest and the index must describe the same set; and a catalog’s location is dropped entirely from the published index, not left as a bare kind, which a diff against an older index had called “moved”. With this, every page the generator renders has a writer; what remains is for the build to call the writer and copy the files, and for the generator to go.

2026-10-15, the build calls the writer; the generator goes. chartbook/sitefiles.py, write_site(), replaces the generator’s build_all(): it builds the index first (or takes the one the incremental build made), then writes a page for every Dataframe, Chart, Model and Pipeline record of a pipeline the build generates — one the build skips, or an incremental build keeps, has none written, except a pipeline site’s front page, which is the site’s — and the catalog’s own pages; then it copies the files the index names beside them, from the records rather than from the manifests: a chart’s HTML to the download folder and to _static, a notebook to cb/notebooks/, a note to cb/, a dataframe’s one file to the download folder when downloads are enabled; gives a copied notebook a title cell if it lacks one, from its record’s name; copies the theme’s own files and, in the pipeline theme, the pipeline’s own site pages from site_dir. The page skeletons and helpers the writer had imported from the generator (the model page’s two template strings, the freshness fact, the two number formats, the YAML escape, the front-matter check, the per-column date range) live in the writer now; markdown_generator.py is deleted. The golden tests keep their shape — build the site with the CLI, compare each page with the writer’s — and now guard the plumbing: that the build writes every page at its path and leaves out what it should. Two behaviours changed with it, both proposed: a catalog copies no pipeline’s site pages (the generator had copied the first pipeline’s to the catalog’s root, where no front page listed them), and the generated folders cb/download_chart/<slug>/, _static/<slug>/ and cb/notebooks/<slug>/ exist only when something is copied into them. An adversarial review of the step found a regression and two smaller things: an incremental rebuild had deleted a reused pipeline’s notes — nothing of a reused pipeline was copied, and the sync removes what a build did not write, while the front page, written on every build, still listed them; a reused pipeline’s notes are copied again now, since the page that lists them is. Notes are copied in the pipeline theme only, as the generator did (a catalog has no page that lists them, and two pipelines’ notes of one name would collide at cb/<name>.md). And the theme files to leave out are matched against their path under the theme folder, not the machine’s whole path, so a project under a folder named models gets its theme (the generator had the same fault).

What this does not decide#

Whether a site built later for a past snapshot (the direction on the vocabulary page) reads the write-ups from git at the snapshot’s commit, or from the store; the Build record’s full shape; whether the catalog’s diagnostics are computed by the writer or recorded by the build. Each is marked above where it arises.