Skip to content

Split the documentation by surface, and take OpenDice 1.3.0 - #1

Merged
SirDarcanos merged 10 commits into
mainfrom
docs/split-by-surface
Aug 6, 2026
Merged

SirDarcanos merged 10 commits into
mainfrom
docs/split-by-surface

Conversation

@SirDarcanos

Copy link
Copy Markdown
Owner

Six commits, each standing on its own.

Split the documentation by surface. The docs treated Rollful as though the package and the API were two halves of one product. They are not: Rollful is the REST API, OpenDice is the npm package it rolls with. /docs now covers the package, /docs/api the API, one sidebar group each.

The REST API gained a first page. It opened on "Reading a result" — reference material with nothing before it — so Making a call now shows a first request in curl, JavaScript, Python, PHP, Go and Ruby, the response, the POST body and the batch route. The generated endpoints moved under /docs/api/endpoints to leave /docs/api free for it, and the reference moved off /reference, which was Scalar's mount point. Its snippets cover every client the generator supports rather than fetch and curl alone, and a local Starlight plugin drops the "Overview" links it insists on adding — each pointed at a page the sidebar already showed.

OpenDice 1.3.0 honours the count in front of adv and dis, so 4d20adv throws four d20 and keeps the highest rather than being cut back to two. A count of 1 is deprecated: 2d20adv is what 1d20adv means. The dice budget reads the parsed count, which the parser keeps in step with what is thrown, and a batch test pins the two together.

One code theme. The config asked Starlight to use the site's palette theme and it never did — starlight-openapi replaces the whole expressiveCode key while setting removeUnusedThemes, silently, since a missing theme falls back. Night Owl is now the theme in both places, and the marketing page's blocks are drawn by Expressive Code itself so the frames match rather than approximate.

A 404 page, answering for every address the site does not have, the documentation's included. Unmatched requests reached an empty body before: the Worker serves assets with no page to fall back to.

A card for the socials. A shared link unfurled as a bare title, and Starlight was claiming a summary_large_image with no image to fill it.

Verified

  • 31/31 tests, astro check clean, prettier clean, check-build clean
  • 15 pages built, every internal link in the build resolves
  • Both landing pages, the endpoint pages, the 404 and the social meta checked in a browser

🤖 Generated with Claude Code

SirDarcanos and others added 10 commits August 6, 2026 14:23
The reference needs the document at build time. Fetching the deployed one would
have documented the previous version until the API caught up, since both deploy
from the same commit, and would have made the site unbuildable whenever the API
was down.

The Worker produces it instead: esbuild bundles the app, the script calls its own
/openapi.json route, and API_VERSION comes from the same wrangler config the
deployed Worker reads. So the document describes what the API actually serves
rather than a second description maintained beside it.

`npm run build` regenerates it, and CI fails if the committed copy is stale, so a
change to the API that never reached the document cannot ship.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Starlight, at /docs, covering getting started, the formula grammar, reading a
result, limits and errors. Starlight owns only what sits under the nested docs
directory, so the marketing page keeps its own route and its own look.

The grammar page closes a gap the marketing page opened: cutting the grammar
table from the home page left five preset chips on the roller as the only place
the syntax was visible.

Limits is MDX so it can read `@rollful/schema` directly. Every other place these
numbers appear is generated from that file, and a documentation page retyping
them would be the one copy free to drift.

The palette is mapped onto Starlight's variables, and the title is overridden to
link back out of the docs — Starlight's own knows only about the documentation,
which would strand a reader inside it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The site had grown three shells: the marketing page, Starlight for the docs, and
Scalar for the reference — three sidebars, three searches, three typographic
systems sharing only a palette. The reference is now generated from the OpenAPI
document by starlight-openapi, so the documentation and the reference are one
site with one sidebar, one search and one theme.

The reference is read-only in exchange. starlight-openapi ships no HTTP client —
no fetch, XMLHttpRequest or axios anywhere in its dist — so it offers copyable
snippets in many languages where Scalar could send the request. The home page
roller still exercises the live API, and every endpoint is a one-line curl.
/reference/ keeps its URL, so existing links and the sitemap still resolve.

Two things this broke that had to move with it. Starlight renders its own
document, so Base.astro never runs there and analytics were reaching the
marketing page alone; the Fathom snippet now has one definition serving both.
And the site deploy checked for Scalar's markup, which would have failed every
future deploy.

SiteHeader is gone with the page that used it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Prettier reformatted apps/site/src/openapi.json, which CI then compared against
a freshly generated copy and called stale. The file is a build artifact; its
shape is the generator's to decide.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The documentation covered "Rollful" as though the package and the API were
two halves of one product. They are not: Rollful is the REST API, and
OpenDice is the npm package it rolls with. /docs now covers the package and
/docs/api the API, one sidebar group each, so the first decision a reader
makes is the first thing they see.

The REST API gained a first page. It opened on "Reading a result" — reference
material with nothing before it — and the quick start was buried in the
generated reference. "Making a call" now shows a first request in curl,
JavaScript, Python, PHP, Go and Ruby, the response, the POST body, and the
batch route. The generated endpoints moved under /docs/api/endpoints to leave
/docs/api free for it, and the OpenAPI document's introduction stopped
repeating the pages around it.

The reference also moved off /reference, which was where Scalar had been
mounted, and is called the REST API rather than the API reference. Its
snippets cover every client the generator supports rather than fetch and curl
alone, and a local Starlight plugin drops the "Overview" links it insists on
adding, since each one pointed at a page the sidebar was already showing.

OpenDice 1.3.0 honours the count written in front of adv and dis, so 4d20adv
throws four d20 and keeps the highest rather than being cut back to two. A
count of 1 is deprecated: 2d20adv is what 1d20adv means, and the docs, the
home page presets and the tests say so now. The dice budget reads the parsed
count, which the parser keeps in step with what is thrown, and a batch test
pins the two together.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The site carried a syntax theme written from its palette, and the config
asked Starlight to use it too. It never did: starlight-openapi sets
removeUnusedThemes on a config object it builds fresh rather than on the one
it was handed, so whatever expressiveCode was configured is replaced and the
themes go with it — silently, since a missing theme falls back. The
documentation rendered in Night Owl throughout while the marketing page
rendered in the palette, and a snippet changed appearance between the two.

Night Owl is now the theme in both places. Shiki bundles it under the same
names Starlight uses, so the marketing page names them and nothing is
vendored or configured on the Starlight side.

The marketing page also frames code the way Expressive Code does: a shell
command shows the three dots of a terminal, anything else a tab with its
name, and the copy button waits in the corner until the block is hovered or
something in it is focused. Expressive Code itself is not reused for this.
Its component reaches the page only through Starlight's, which brings
Starlight's stylesheet along, and that reset outranks Tailwind's layered
utilities and flattens the page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The frames on the marketing page were the site's own: a header strip, a label
and a copy button, matching the documentation in colour but not in shape. They
are now drawn by Expressive Code, which draws the documentation's, so a shell
command shows the terminal dots, anything else a tab with its name, and the
copy button waits in the corner until the block is hovered.

The component is imported from astro-expressive-code rather than from
Starlight, which re-exports it. Starlight's barrel pulls in eleven other
components and its stylesheet with them, and that reset outranks Tailwind's
layered utilities and flattens the page.

Starlight has Expressive Code take three greys from the palette rather than
from the syntax theme, and one of them reaches the frame through a color-mix.
Those three are declared on :root here, where Expressive Code resolves its own
variables — scoped any tighter, the mix is invalid, the border shorthand
holding it is dropped, and the frame renders without an outline or a
background.

The roller is framed from the same variables, so the panel beside the code
blocks is the same panel.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The last rounded corners in the hero, beside code blocks and a roller that
are not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Worker serves assets and nothing else, and the default for a request that
matches none of them is an empty 404. Astro builds 404.html, and
not_found_handling serves it.

One page covers the whole site. Starlight's own 404 route is already off, so
the documentation falls through to this rather than keeping a second one that
would have to be dressed the same.

It names the address that was asked for, which only the browser knows since
one page answers for all of them, and sets it as text rather than as markup —
it is whatever was typed into the bar. The layout carries noindex and no
canonical: a page served at every address has no one address to name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A link to the site unfurled as a bare title: the layout wrote og: tags by
hand and left the image out, because there was none to point at, and Starlight
was claiming a summary_large_image with nothing to fill it.

The card is the site's own furniture — the wordmark, the headline, the palette
and the oversized die — over one roll showing its working, since that is what
the API is for. The dropped die is dimmed rather than struck through: the
rasteriser ignores text-decoration, and a line drawn over the glyph would need
coordinates that hold only for the fonts on one machine.

The SVG is the source and build-og.mjs rasterises it, but the PNG is committed
and the script is run by hand. Type is drawn with the fonts of whatever machine
draws it, so building the card during a deploy would redraw it in a CI
runner's fonts and change the card without anyone asking.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@SirDarcanos
SirDarcanos merged commit 078d9f3 into main Aug 6, 2026
1 check passed
@SirDarcanos
SirDarcanos deleted the docs/split-by-surface branch August 6, 2026 13:26
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