Repository navigation
Rebuild the docs site with working search and a structure organised by reader - #19
Merged
Merged
Conversation
Merge the duplicate VM, extension and utility API pages into the API reference, fold the editor tour, custom blocks and packaging pages into their canonical pages, delete the moved stubs, and add overview pages for Advanced features and the community site. Every old path redirects.
The index is written by a local plugin after docusaurus build, so it needs no external service and works offline and inside the editor's Help window. Ctrl or Cmd+K and / open it, except that Ctrl or Cmd+K stays with the editor's spotlight when the docs are embedded.
Bring back the navbar with the five sections and search, cap the text width, set a type scale, flatten tables, code blocks and admonitions, add an on this page heading and prev and next links, and give standalone visitors a colour mode switch that hides when the editor embeds the docs.
scripts/check-inbound-links.mjs reads the docs links in a sibling scratch-gui checkout (or SCRATCH_GUI_DIR), adds the committed list of every path the site has served, and checks each against the build, following redirect pages. npm run check runs it and CI runs it after the build, on Node 22.
The architecture page says scratch-gui builds with Vite, the deploy page describes how the Cloudflare build fetches the docs tarball, the introduction links to the current page names, and search results are resolved against the site root so their section labels show.
AGENTS.md is in the global gitignore on this machine, so it is added with -f. The search launcher also drops its shortcut hint on touch screens.
Muted text mixes 94% of the editor's text colour when embedded and 74% standalone, and links and active items use the accent with its lightness capped (light) or floored (dark), so any editor accent stays readable.
Tab cycles through the search window's controls, a status region announces the result count, and aria-controls is only set while results are shown. When a query has few exact matches, shorter prefixes are tried and shown under an honest close matches label. /search/?q= opens the search prefilled, and the shortcut hint is hidden on touch screens.
Drop Pagefind's unused UI bundles, scope the webpack expression setting to the loader module, and make the inbound link check verify anchors, following redirects.
The stage page now explains turbo mode and the three ways to toggle it, the menu bar and URL parameter pages link to it, the API reference title is in sentence case, and Applying code no longer repeats Rename a Stage variable.
Deploying docs with
|
| Latest commit: |
43af278
|
| Status: | ⚡️ Build in progress... |
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.
A ground-up rebuild of the docs site. The old one was hard to read through and search didn't work at all: it pointed at an Algolia index that doesn't exist ("Index mistwarp does not exist"). Stacked on #18.
Search that works. Pagefind builds the index during
docusaurus build, with no outside service, so it works offline and inside the editor's Help window. Results group matching headings under each page and link straight to them. When a query has no exact match it retries with prefixes and labels the results as close matches: "packger" finds the packager pages. Ctrl/Cmd+K and/open it. Inside the Help window, Ctrl/Cmd+K still goes to the editor's spotlight. The dialog is keyboard navigable, traps focus, and announces result counts to screen readers. The first query loads about 120 KB, later ones 1 to 40 KB.Organised by reader, not by folder. Five sections, each with an overview page: Using MistWarp, Extensions, Packager, Contributing and Backend. Sidebars are written out in
sidebars.jsinstead of generated from folder names. There's a real landing page with search and a card per section.Merged and removed. The two VM API pages are one page now, and so are the two utility pages. The extension "Scratch object" page moved into the Extension API page, and the editor tour, custom blocks and packaging pages joined the pages that cover them. Stub pages are gone. Titles are in sentence case. Turbo mode now has a real explanation (it was described as a setting, which was wrong).
Readable. Comfortable line length and type scale, a visible "On this page", prev and next links, and readable tables and code. Every text colour is at least 4.5:1 contrast in both themes, standalone and inside the Help window; the lowest is 4.74. Notes use a tinted background and an icon, with no side stripes. Standalone visitors get a colour mode switch, hidden when embedded.
Nothing breaks.
npm run check(scripts/check-inbound-links.mjs) checks all 150 inbound paths, anchors included, against the build and a scratch-gui checkout, and CI runs it.scripts/pack-build.mjs,baseUrl: '/docs/'andtrailingSlashare unchanged, so the tarball scratch-gui's Cloudflare build downloads keeps its shape.?docusaurus-theme=dark|light, which the Help window can use instead of writinglocalStorage.themein a follow-up.AGENTS.md tells coding agents where pages go, the writing rules and the URL contract.
A typo falls back to close matches:
Phone width, dark:
Inside the editor's Help window (880 px, editor dark theme), searching:
Checks:
npm run build(broken links, anchors and Markdown links fail the build) andnpm run checkpass. Chromium and Firefox at 1280 and 390, light and dark, plus a Help window harness. An independent review checked the URL contract, deploy, Help window, search, contrast and content, and its findings are all addressed.