Repository navigation
Split the documentation by surface, and take OpenDice 1.3.0 - #1
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
/docsnow covers the package,/docs/apithe 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/endpointsto leave/docs/apifree for it, and the reference moved off/reference, which was Scalar's mount point. Its snippets cover every client the generator supports rather thanfetchandcurlalone, 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
advanddis, so4d20advthrows four d20 and keeps the highest rather than being cut back to two. A count of 1 is deprecated:2d20advis what1d20advmeans. 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-openapireplaces the wholeexpressiveCodekey while settingremoveUnusedThemes, 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_imagewith no image to fill it.Verified
astro checkclean, prettier clean,check-buildclean🤖 Generated with Claude Code