📖 docs: add Spektacular and port its docs from both repos - #14
Merged
Merged
Conversation
Spektacular (github.com/hivecommons/spektacular, canonical site spektacular.dev) transferred into hivecommons from jumppad-labs. Wire it into the sibling-docs sync alongside hotshot, pluk, rationguard and promptargs: - sync-sibling-docs.ts: new project entry (README.md required, docs/knowledge-base.md optional; SPEKTACULAR_DOCS_REF override) and a jumppad-labs -> hivecommons rewrite for repo sub-paths only (Go module path and Homebrew tap still live under jumppad-labs) - versions.ts / shared.json: extend ProjectId, add versions + projects entries, related-projects card and edit URL - page-map, [...slug] layout/page, sitemap, sidebar, source actions, edit link, related projects: enumerate spektacular everywhere the other siblings are - netlify.toml: /docs/spektacular root redirects - docs/content/spektacular: committed fallback copies used when the sync is unreachable Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Andrew Anderson <andy@clubanderson.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
…clean Extend the sibling-docs sync so the Spektacular section on docs.hivecommons.dev carries the full documentation set: - Overview (README) and Knowledge base from hivecommons/spektacular - "Getting started" and "Dealing with unknown criteria" tutorials from hivecommons/spektacular-website (Astro MDX), converted to Markdown by the new scripts/mdx-to-markdown.ts: imports/exports stripped, <Step> and <AgentBlock> rendered as headed sections, <YouTubeVideo> as a timestamped link, unknown components flattened to their text with a note in the sync log, site-absolute links pointed at spektacular.dev, and referenced images copied under docs/content/spektacular/images/ - a second source per project with its own ref (SPEKTACULAR_WEBSITE_DOCS_REF) - an "also published at spektacular.dev" canonical note on every page - sidebar: Overview / Tutorials / Guides Make the synced content satisfy markdownlint (MD031/MD040) at the source instead of hand-editing generated files: scripts/markdown-fences.ts adds a language to bare fences and blank lines around them, applied by both sync scripts. The committed copies are regenerated by running the syncs (this also brings the Hive pages up to the v5 source that #13 retargeted). CI fixes for the three pre-existing red checks: - Vitest: run on Node 22 (jsdom 30 pulls in undici 8, which needs >= 22.19; Node 20 failed with "webidl.util.markAsUncloneable is not a function") - ESLint: drop eslint-disable comments for the removed rule @typescript-eslint/no-throw-literal - markdownlint: fence normalisation above Tests: fence normaliser, MDX converter, and the sibling sync config (every project enumerated, Spektacular pulling from both repos). Signed-off-by: Andrew Anderson <andy@clubanderson.com>
clubanderson
changed the title
The Netlify site is not producing deploy previews for pull requests, so CI is the only place the converted MDX pages are proven to compile. Render the four Spektacular routes through the real docs page (content -> MDX compile -> evaluate -> DocsLayout) and fail if any of them falls back to the plain-text <pre> path, loses its H1, or does not route its tutorial screenshots through /docs-images/. Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…oes not read it as JSX A hard wrap inside the inline code left `<project|repo|all>` at column 0, which the MDX compiler parses as a JSX tag and fails; the page then rendered as a raw <pre> dump. Same fix goes upstream to hivecommons/spektacular. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Andrew Anderson <andy@clubanderson.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
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.
Summary
Adds Spektacular as a sibling project on docs.hivecommons.dev and ports its documentation from both of its repositories.
Pages (all regenerated at build by
scripts/sync-sibling-docs.ts)/docs/spektacular/overview/introductionhivecommons/spektacularREADME.md/docs/spektacular/tutorials/getting-startedhivecommons/spektacular-websitesrc/content/tutorials/getting-started.mdx/docs/spektacular/tutorials/unknown-criteriahivecommons/spektacular-websitesrc/content/tutorials/unknown-criteria.mdx/docs/spektacular/guides/knowledge-basehivecommons/spektaculardocs/knowledge-base.mdEvery page carries an "also published at spektacular.dev, which is the canonical copy" note so search engines do not treat this site as the primary copy.
Sync changes
SPEKTACULAR_WEBSITE_DOCS_REF.scripts/mdx-to-markdown.tsconverts Astro MDX to plain Markdown: stripsimport/export, renders<Step>as### Step N: heading,<AgentBlock>as a labelled section (Claude Code / Bob / Codex),<YouTubeVideo>as a timestamped link, flattens any unknown component to its text and logs a note, rewrites site-absolute links to spektacular.dev, escapes stray braces, and hands/images/...paths to the sync, which copies them intodocs/content/spektacular/images/(28 tutorial screenshots).scripts/markdown-fences.tsnormalises fences (MD040 language, MD031 blank lines) in both sync scripts, so synced content passes markdownlint at the source. The committed copies were regenerated by running the syncs; this also brings the Hive pages up to thev5source that 📖 sync: retarget Hive docs source from v4 to v5 (hold until first v5 stable promotion) #13 retargeted (the committed copies were still fromv4).CI fixes (all three were already red on
main)engines >= 22.19); on Node 20 the three jsdom suites failed to fork withwebidl.util.markAsUncloneable is not a function.eslint-disablecomments for@typescript-eslint/no-throw-literal, a rule that no longer exists (and is not enabled).Tests
scripts/markdown-fences.test.ts,scripts/mdx-to-markdown.test.ts,scripts/sync-sibling-docs.test.ts(project enumeration, dual-source config, headers, link and brand rewriting).🤖 Generated with Claude Code