docs: migrate from spectaql to Magidoc - #4
Merged
Conversation
Replace the spectaql + hand-built landing setup with Magidoc (carbon-multi-page), a modern GraphQL-native static docs generator. It produces a page-per-operation/type reference with auto-generated example queries and cross-linked types, alongside the narrative guides — a big visual and usability upgrade, still fully static. - magidoc.mjs: SDL introspection from ./schema.graphql, Flash branding (logo, favicon, 'Flash API' title), header links, and queryGenerationFactories covering the schema's ~40 custom scalars so each operation renders a realistic sample query. - guides/: the landing content ported to Markdown guide pages (introduction, getting-started, authentication, api-keys, examples, errors). The API Keys guide is new (FIP-07). - build: 'npm run build' now fetch-schema (prod) -> rm -rf public -> magidoc generate. Output still lands in public/ for the existing DigitalOcean deploy; public/ and docs/ are now build artifacts (gitignored). - Removes the dead spectaql pipeline: spectaql-config.yml, src/ (old landing + version-selector UI), build-versions.js, VERSION.md, and the committed spectaql build output. The multi-version scaffolding was cosmetic (all versions pointed at the same prod schema) and is superseded. The schema reference is generated from the production API, so the apiKey* operations appear once the FIP-07 feature ships to prod; the API Keys narrative guide is available immediately. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
added 2 commits
July 12, 2026 21:20
npm ci was out of sync (lock still carried the removed doc-generator dependency trees), which would fail the CI deploy build. Regenerated.
@magidoc/plugin-starter-variables imports lodash but was resolving it transitively via the (now-removed) spectaql/@2fd/graphdoc trees. Declare it explicitly so a clean 'npm ci' (as CI runs) resolves it. Verified: clean npm ci + magidoc generate builds all 6 guides + reference.
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
1 participant
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.
Replaces the spectaql + hand-built landing setup with Magidoc (
carbon-multi-page) — a modern, GraphQL-native static docs generator. Big visual + usability upgrade, still fully static (deploys unchanged).Why Magidoc
Evaluated Magidoc vs Astro Starlight against the real Flash schema. Magidoc won on the reference — the thing that's hardest to do well: a page per operation and type, each with the description, cross-linked argument/response types, and an auto-generated example query (Query/Variables/Response tabs). Starlight's GraphQL reference is a bolt-on (one giant table page). Magidoc is a near drop-in for the spectaql half.
What changed
magidoc.mjs— SDL introspection from./schema.graphql; Flash branding (logo, favicon, "Flash API"); header links (Interactive Explorer, getflash.io);queryGenerationFactoriescovering the schema's ~40 custom scalars so every operation renders a realistic sample.guides/— the landing content ported to Markdown:introduction,getting-started,authentication,api-keys(new, FIP-07),examples,errors. These appear as a "Guides" section alongside the generated Queries/Mutations/Subscriptions/Types.npm run buildis nowfetch-schema(prod) →rm -rf public→magidoc generate. Output still lands inpublic/for the existing DigitalOcean deploy;public/anddocs/are now build artifacts (gitignored), which is why this diff shows large deletions of previously-committed build output.spectaql-config.yml,src/(old landing + version-selector UI),build-versions.js,VERSION.md. The multi-version scaffolding was cosmetic (every version pointed at the same prod schema) and is superseded — flag if you want real per-version docs and I'll wire Magidoc per-version.Notes
apiKey*operations show up automatically once FIP-07 ships to prod. The API Keys narrative guide is live immediately.docs/fill-landing-exampleseffort (the landing is now Markdown guides).🤖 Generated with Claude Code