Skip to content

Read and search RESTest's documentation on the site, at the released version - #2

Merged
ssegura merged 1 commit into
mainfrom
feat/m12-4-documentation-site
Nov 5, 2026
Merged

ssegura merged 1 commit into
mainfrom
feat/m12-4-documentation-site

Conversation

@ssegura

@ssegura ssegura commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Related: #1, the look this builds on. A pull request in RESTest follows once the site is live (see "Open questions").

What you can do now that you could not before

Read and search RESTest's documentation as a website: the manual, every reference page and every decision record of the latest release, v2.4.0, with a menu built from RESTest's own indexes, search with no outside service, and the light and dark look of the site. Nothing in RESTest changed for it, and an llms.txt points a coding agent at every page's Markdown in that version.

Try it yourself

With Node 26 and git, from a clean checkout:

git clone https://github.com/isa-group/restest-site && cd restest-site && git switch feat/m12-4-documentation-site
npm ci
npm test
npm run build
npm run preview        # then open http://localhost:4321/restest-site/docs/

Real output, from a fresh clone of this branch (the build's list of pages left out):

ℹ tests 47
ℹ pass 47
ℹ fail 0

Copied 72 pages and 3 images of RESTest 2.4.0
 validating links
· All internal links are valid. ·
[build] 73 page(s) built in 1.59s
[build] Complete!

In the browser: the manual's chapter 4 is at /restest-site/docs/manual/reading-what-a-run-says/; search for "exit code"; switch between following the system, light and dark with the three buttons at the top right; narrow the window to a phone's width. http://localhost:4321/restest-site/llms.txt is the index for agents.

To see the build refuse a page, break a link in a copy of RESTest and build from it:

git clone --depth 1 --branch v2.4.0 https://github.com/isa-group/RESTest ../RESTest
printf '\nSee [the exit codes](command-lines.md).\n' >> ../RESTest/docs/faults.md
npm run sync -- --from ../RESTest
sync-docs: docs/faults.md: links to command-lines.md, which is not in RESTest at master

A link to a heading that does not exist, command-line.md#exit-code, gets past that step and fails the build instead:

[ERROR] [starlight-links-validator] Links validation failed.
    ╭─ docs/faults/index.md
539 | /restest-site/docs/command-line/#exit-code
    ·                                      ╰── invalid hash
· Found 1 invalid link in 1 file. ·

Undo it with git -C ../RESTest checkout docs/faults.md. npm run sync -- --ref master && npx astro build builds from what the next version will be.

How it works

Before each build, a script takes RESTest at the version written in the one-line file restest-version (v2.4.0). It never changes RESTest's files: it reads the Markdown in docs/ and the three files at the root that docs/README.md links, and writes each as a page of the site, with its first # heading as the title and every link pointed at the site. A link to another page goes to that page; to an image, to a copy of it; to any other file of RESTest, such as LICENSE, to GitHub at that version. Only the links change: the rest of each file stays byte for byte as RESTest has it.

The menu on the left is read from RESTest's two indexes: the numbered list of chapters in docs/manual/README.md, and one group per ## section of docs/README.md, with that section's table giving the entries. A page that is in neither index, a link to nothing, a page with no title or an index of another shape stops the build, naming the file in RESTest, so that a change in RESTest cannot quietly leave a page out of the site.

When RESTest publishes a version, a workflow of RESTest's, added in its follow-up pull request, will write the new version into restest-version here. That commit, like any other on main, rebuilds the site and publishes it on GitHub Pages. Once a week the site is also built from RESTest's master, without publishing it, so that a change there that would break the site is known before the next release.

What changed in the code

  • scripts/sync-docs.mjs — the step that copies the documentation: takes RESTest at a version (--ref) or from a folder (--from), keeps the shallow clone in .restest/ between runs, and writes the pages, the images, the menu and llms.txt. Git is called with arguments, never through a shell, and a version is accepted only if it is a plain git name.
  • scripts/lib/ — what that step does, one file per job: pages.mjs (which files are pages, their address, their title), links.mjs (where each link leads, including src, srcset and href in raw HTML), sidebar.mjs (the menu from the two indexes), llms.mjs (the index for agents), markdown.mjs (parsing, and changing only the characters of a link's address) and refs.mjs (which version names are accepted).
  • astro.config.mjs, site.config.mjs, src/content.config.ts — the site with Starlight, at https://isa-group.github.io/restest-site/, with / leading to /docs/ until the landing page exists.
  • src/styles/docs.css — Starlight in the look of pull request The site's look: colours light and dark, three typefaces and RESTest's logo in SVG #1: its colours and type taken from tokens.css, nothing under 14 px, the menu, titles and "On this page" as the mock-up drew them, and on a wide screen the menu, the text and "On this page" together in the middle of the window.
  • src/components/ThemeSelect.astro — the theme in one click, with three buttons, in place of Starlight's drop-down; in the header on a phone too.
  • .github/workflows/site.yml — builds every pull request, publishes main on GitHub Pages, and builds weekly from master without publishing. Actions are pinned by commit.
  • restest-version, .nvmrc, public/favicon.svg, README.md — the version to publish, Node 26, the logo's check as the icon, and how to build and what the step reads and writes.
  • test/ — 47 tests with node --test; those of the menu read RESTest's own two indexes at v2.4.0, copied as fixtures.

Left for later: drawing Mermaid diagrams, before 2.5.0, the first version with one; the full header of the mock-up, with the landing page; breadcrumbs, if wanted.

Evidence

  • Tests: 47 pass (npm test), covering addresses, titles, links in Markdown and raw HTML, the menu from both indexes, llms.txt and the accepted version names, with each kind of malformed input the build refuses.
  • Architecture tests: not applicable; nothing in RESTest changes.
  • Mutation score: not applicable.
  • Per-request overhead: not applicable.
  • Smoke run: not applicable.
  • Idle time: not applicable.
  • Artefact: the site built from v2.4.0 (72 pages and 3 images copied, 73 pages built) and from master (75 pages and 5 images, 76 built), every internal link and heading valid. Measured in Chrome over seven pages, in both themes, at desktop width and at 375 px: no text under 14 px, search included, and the lowest contrast 6.53 : 1 in dark and 5.44 : 1 in light. No horizontal scrolling from 320 px to 2560 px. All 26 links of llms.txt answer 200. npm audit: 0 vulnerabilities; actionlint: clean.

Decisions taken

  • The site publishes the latest release, not master (maintainer), so it describes what users have installed. The five documentation pull requests merged since v2.4.0 appear with 2.5.0; npm run sync -- --ref master shows them now.
  • RESTest tells the site of a new version by writing restest-version with a deploy key, when a release is published and only if the version is higher (maintainer), as it already does for Homebrew and jbang: no personal token to expire, no question to GitHub's API, and the same commit always gives the same pages. RESTest's release.yml only leaves a draft, so a trigger there would have rebuilt the previous version.
  • The menu's group names are RESTest's ## headings (maintainer). RESTest's follow-up pull request renames "Using RESTest" to "Reference"; until then the site says "Using RESTest".
  • A chapter loses its number in its address (/docs/manual/a-first-run/), so that inserting a chapter does not move the others; decision records keep theirs, which is what cites them.
  • Addresses and heading anchors are made with github-slugger (ISC), the one GitHub and Astro use, so #exit-codes means the same on both.
  • RESTest's logo <img> is dropped from its README page: it is black on opaque white, a white box in the dark theme, and the header shows the logo already. The site finds it by its file name, RESTLogo_Black.png; RESTest's follow-up ADR records that.
  • A <picture> with a dark source becomes two images, each hidden in the other theme, so it follows the theme the reader picks rather than only the system's.
  • Astro's smart punctuation is off: it turned --auth into –auth and straight quotes into curly ones, which GitHub never does.
  • Starlight's previous and next links are off (pagination: false): the chapters of the manual already end by linking the next one, and between reference pages the order means nothing.
  • Looks chosen by the maintainer at the preview: every paragraph at one size, the first included; the menu, the text and "On this page" centred together on wide screens, as the documentation sites of VitePress and Material for MkDocs do, with the header lined up on them; the theme as three buttons, as in the mock-up, on a phone in the header; the menu's group titles in bold, with a line between groups.
  • Departures from the mock-up kept: no breadcrumbs; "Edit page" at the foot, where Starlight puts it; no "Docs" beside the logo nor links to the landing page and the showcase, which come with them; groups "Overview" and "Building RESTest", which the mock-up does not show.
  • Two warnings remain in the build, about an i18n collection and a 404 entry; both come from Starlight with a single language, and defining the collection to silence the first adds another.
  • No dependabot.yml: RESTest keeps automatic updates off, and Starlight is still 0.x.
  • Not taken from reviewers: a sparse checkout of RESTest, since the shallow clone is small and kept between runs; dropping --sl-color-bg, kept so that the page's background does not depend on how Starlight derives it; and dropping cancel-in-progress: false, kept so that the workflow says a publication is never cut short.

Open questions

  • GitHub Pages must be enabled before merging (Settings → Pages → Source: GitHub Actions), or the first publication fails.
  • Should the site also publish master's documentation, as a "next" version beside the released one? It is not in this pull request.
  • Then RESTest's pull request: an ADR saying why the site lives outside and which shape of the two indexes it depends on, the link in its README, a row in AGENTS.md, the workflow that writes restest-version, the rename to "Reference", and a line of docs/schemas.md that starts with > plan.yaml and so shows as a quote, on GitHub too.

  • Targets main
  • English throughout, including comments and test names
  • The hard rules in RESTest's AGENTS.md hold

🤖 Generated with Claude Code

…earchable, in the site's look

Starlight builds /docs from RESTest's own Markdown at the version in restest-version. Before each
build, scripts/sync-docs.mjs fetches that version, takes each page's title from its first heading,
points every link at the site (or at GitHub at that version when it leaves the pages), copies the
images the pages show, and reads the sidebar from docs/README.md and docs/manual/README.md. It fails,
naming RESTest's file, on a page with no title, a link to nothing, two files at one address, an index
of another shape, or a page in no index. Pagefind searches the pages, /llms.txt lists them for coding
agents, and a workflow builds every pull request, publishes main on GitHub Pages, and builds from
RESTest's master every week.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura
ssegura merged commit 92d8b47 into main Nov 5, 2026
3 checks passed
ssegura added a commit to isa-group/RESTest that referenced this pull request Nov 6, 2026
…lease once it is published (#439)

**Related:** isa-group/restest-site#2, which
publishes the documentation as a website, now live at
https://isa-group.github.io/restest-site/docs/.

## What you can do now that you could not before

Read and search RESTest's documentation at one address,
https://isa-group.github.io/restest-site/docs/, which the README and the
skill for coding agents now give. Once this is merged and its key is set
up, publishing a release moves the site on to that release by itself and
checks that it did; and a pull request that would leave the site unable
to build — a page in no index, an index of another shape, a page with no
title, a link to a page's own title — fails here, naming the file,
rather than after the release.

## Try it yourself

With Java and git, from a clean clone:

```bash
git clone --branch feat/m12-4-documentation-site https://github.com/isa-group/RESTest.git restest-docs-site
cd restest-docs-site
./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \
  -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Tests run:.*in io|BUILD'
```

```
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.179 s -- in io.restest.arch.DocumentationSiteTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.044 s -- in io.restest.arch.DocumentedLinksTest
[INFO] BUILD SUCCESS
```

Now add a page that no index lists, and a link to a page's own title,
which the site shows above the page rather than as a heading:

```bash
printf '# Faults, again\n\nThe same page twice.\n' > docs/faults-again.md
printf '\nSee [the command line](command-line.md#the-command-line).\n' >> docs/faults.md
./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \
  -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Expecting empty|BUILD' | sort -u
```

```
Expecting empty but was: ["docs/README.md lists no entry for docs/faults-again.md, so the website's menu would not reach it; every page needs one, in it or in docs/manual/README.md"]
Expecting empty but was: ["docs/faults.md links to command-line.md#the-command-line, and docs/command-line.md has no heading by that name"]
[INFO] BUILD FAILURE
```

Undo it with `git checkout docs/faults.md && rm docs/faults-again.md`.
With Node 26, the site builds from this branch, and its first group is
named "Reference":

```bash
git clone https://github.com/isa-group/restest-site ../restest-site && cd ../restest-site
npm ci && npm run sync -- --from ../restest-docs-site && npx astro build | grep -E 'valid|built in'
grep -o '"label": *"Reference"' src/generated/sidebar.json
```

```
Copied 76 pages and 5 images of RESTest at master, from …/restest-docs-site
· All internal links are valid. ·
[build] 77 page(s) built in 1.35s
"label": "Reference"
```

The workflow cannot be tried before it is on `master` and its key is set
up (see "Open questions").

## How it works

The site lives in its own repository, `isa-group/restest-site`. Before
each build it takes RESTest at the release named in its one-line file
`restest-version` and reads the Markdown under `docs/`, `README.md`,
`AGENTS.md` and `CONTRIBUTING.md` as they are; its menu comes from the
two indexes, the manual's numbered list of chapters and one group per
`##` section of `docs/README.md`. Nothing of the site is in RESTest's
build. ADR-0047 says why it is done this way, and everything in the
pages the site relies on.

When a release is published, the new workflow `documentation-site.yml`
writes its tag into the site's `restest-version` with a deploy key, as
`homebrew.yml` and `jbang.yml` write into the tap and the catalog: never
over a higher version, and not again when it is there. That commit makes
the site build from the new tag and publish it; the workflow then waits
until the site's `llms.txt` names the version.

A tag never changes, so a release whose pages the site cannot build
would leave the site unable to publish anything until the site is
changed. Two things keep that from happening: `DocumentationSiteTest`
holds every pull request to the rules the site builds by, and before a
tag the site is built by hand from `master` (a new step in the release
steps of `docs/ci.md`).

## What changed in the code

- `.github/workflows/documentation-site.yml` — three jobs: `version`
checks the tag and that it is a published release; `push`, in the
environment `restest-site`, writes the tag into the site with the key
`RESTEST_SITE_KEY`, checking out nothing of RESTest while the key is
loaded; `check-published` waits up to fifteen minutes for the site to
name the version. Started by a release's publication, or by hand with a
tag. No pull-request trigger: it would test a regular expression and
nothing of the writing.
- `restest-arch-tests/.../DocumentationSiteTest.java` — the site's rules
as functions of a folder, applied to the repository and, with
`@TempDir`, to a small documentation broken in 24 ways, each of which
has to be reported. Two rules are stricter than the site: every chapter
of `docs/manual/` is in the manual's list, and each item of that list
starts with its link.
- `DocumentedLinksTest.java` — its link pattern, line reader and
code-fence filter are shared with the new test; and a page's title, its
first `# ` heading, is no longer a heading a link may name, since the
site shows the title above the page rather than as a heading.
- `docs/adr/0047-the-documentation-site.md` — the decision, what the
site depends on, what only the site checks, and the alternatives;
`docs/adr/README.md` lists it, and ADR-0031, whose manual had one
rendering, is amended.
- `docs/ci.md` — five workflows; a section on the documentation site
with its jobs and what to set up once; the release step before the tag;
three runs to see green after publishing; the test in the table of
gates. `docs/DESIGN.md`'s quality gates say the same in a line.
- `docs/README.md` — the first section is now "Reference", the name of
its group on the site.
- `README.md`, `skills/restest/SKILL.md` and its copy in
`docs/for-coding-agents.md` — the site's address, and, for agents,
`llms.txt`.
- `AGENTS.md` — a row of "Where things are" for the site.
- `docs/schemas.md` — a line that began with `> plan.yaml`, which
Markdown, GitHub's included, showed as a quote.

## Evidence

- [x] Tests: one class added, `DocumentationSiteTest`, with three tests
(the repository, a well-formed documentation, and 24 broken ones);
`DocumentedLinksTest` refuses a link to a page's title. `./mvnw verify`:
all green, 157 architecture and documentation tests. — the checks of
this pull request
- [x] Architecture tests: 157, none weakened; the rule on links is
stricter.
- [x] Mutation score: not applicable; no oracle or constraint touched.
- [x] Per-request overhead: not applicable.
- [x] Smoke run: not applicable; nothing a run does changes.
- [x] Idle time: not applicable.
- [x] Artefact: the site built from this branch with its own script
(`npm run sync -- --from <this checkout> && npx astro build`): 76 pages,
every internal link valid, the first group named "Reference".
`actionlint` is clean on the workflow. Its comparison tried against the
site's real `restest-version` (`v2.4.0`): `v2.5.0` and `v2.10.0` are
written, `v2.4.0` is there already, `v2.3.0` is left, and a missing file
is written.

## Decisions taken

- **The site documents the latest release, and is moved on by a deploy
key when one is published** (maintainer), as Homebrew's tap and the
jbang catalog are.
- **The site's address is `isa-group.github.io/restest-site` for now**
(maintainer). When the project has a domain, the README, the skill,
ADR-0047, `docs/ci.md` and the workflow change with it, and GitHub sends
the old address on.
- **`llms.txt` is named in the skill too** (maintainer), so an agent can
read a page the skill does not cover; the skill says it describes the
latest release, which may not be the version run.
- **A release whose pages the site cannot build: the site is changed
until it builds that tag**, and `restest-version` never goes back
(maintainer). Hence the step before every tag: the site built by hand
from `master` after the pull request that prepares the release, since
its weekly build is older than that pull request.
- **`restest-version` holds the tag with its `v`**, the only form the
site reads; versions are compared without it, since `sort -V` would
otherwise rank `v2.4.0` above `2.5.0` and leave the site behind with a
green run.
- **The workflow is `documentation-site.yml`**, not `site.yml`, the name
of the site's own workflow, so that "the run of site.yml" is never
ambiguous.
- **A Java test that restates the site's rules**, rather than running
the site's own build on RESTest's pull requests: that would be one set
of rules, but Node in RESTest's CI and every pull request here depending
on the site's `main`. ADR-0047 lists what only the site checks: links in
raw HTML, reference-style links, links leaving the repository, headings
the site names differently from GitHub, and two files at one address.
- **ADR-0031 is amended**: its manual "has one rendering", which the
site makes untrue.
- Not taken from reviewers: a reusable workflow shared with
`homebrew.yml` and `jbang.yml`, which would change both; a
`version.json` on the site in place of the sentence of `llms.txt` the
workflow waits for, which ADR-0047 records; reporting a missing index as
a problem rather than the failure to read it, which names the file
already.

## Open questions

- **Before 2.5.0 is published, set up once** what `docs/ci.md`
describes: the environment `restest-site` in this repository, limited to
`master` and `v*`, created first; an SSH deploy key with write access on
`isa-group/restest-site`; its private half as `RESTEST_SITE_KEY` in that
environment. Then run the workflow by hand from `master` with `v2.4.0`:
`push` should find the tag there already, and `check-published` should
be green.
- In the site, a small pull request follows: a comment beside
`llms.txt`'s opening sentence saying this workflow waits for it, its
README in the present tense, and Mermaid diagrams before 2.5.0, the
first release with one.

---

- [x] Targets `master`
- [x] English throughout, including comments and test names
- [x] The hard rules in `AGENTS.md` hold

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant