Migrer dokumentasjon fra Sanity til MDX#1795
Draft
oscarcarlstrom wants to merge 8 commits into
Draft
Conversation
Move all documentation content into apps/docs/src/content/ so docs can be authored, reviewed and merged in the same PR as the code they describe. Routes prefer migrated MDX and fall back to Sanity for any unmigrated slug, so existing pages keep working until Sanity is fully retired in a follow-up. Adds the MDX rendering pipeline (remark plugins for fenced code blocks and heading anchors+toc, mdx components map, local Image component), the image-budget lint, the MDX compile check (both gated in CI), and the unreleased-component lifecycle (componentState: unreleased → beta/new via the ci:version hook). Co-Authored-By: Claude <noreply@anthropic.com>
Collapse the duplicate `return 'new'` branches by inverting the predicate — easier to read. Co-Authored-By: Claude <noreply@anthropic.com>
strip-unreleased previously flipped `unreleased → beta` whenever any `propsComponents` entry started with `UNSAFE_`. The auto-generated `component-props.ts` also picks up React Aria Components exports, so an RAC `UNSAFE_PortalProvider` leaking in would incorrectly mark a stable Grunnmuren component as beta. Read packages/react/src directly to build the authoritative set of `UNSAFE_`-prefixed exports from `@obosbbl/grunnmuren-react`, and check propsComponents against that set instead. Co-Authored-By: Claude <noreply@anthropic.com>
|
Adding the Grunnmuren-exports check reintroduced the duplicate return 'new' branches. Fold the early return into the main flow so the default value is only spelled once. Co-Authored-By: Claude <noreply@anthropic.com>
remark-headings only needed a function to turn heading text into a URL-safe id (with dedupe). github-slugger is a whole package for that — a tiny inline function with Unicode-aware character classes does the same job and avoids the dependency. Verified output matches the previous github-slugger run on the sample of headings in the migrated content (`Om komponenten` → `om-komponenten`, `Produkt/Tjenester` → `produkttjenester`, Norwegian characters preserved, duplicate-heading dedupe still works). Co-Authored-By: Claude <noreply@anthropic.com>
`æ`/`å` → `a`, `ø` → `o`, plus NFD normalisation to strip other accents (`é` → `e` etc.) so heading ids stay ASCII and URL-safe. Co-Authored-By: Claude <noreply@anthropic.com>
The MDX path had a duplicate `MdxToc` that rendered identical markup.
Make `TableOfContentsNav` source-agnostic by taking a pre-built
`sections: { href, text }[]` prop, and have both call sites build
their sections inline (from Sanity blocks vs. from the MDX `toc`
export).
Co-Authored-By: Claude <noreply@anthropic.com>
`check-mdx.ts` ran the same MDX compile pipeline as the app, so it was a partial reimplementation of what `vite build` already does. Replace with a `Build docs` step in the PR workflow so MDX errors and any other build regressions are caught together. The deploy build in cd.yml stays the same; this just moves the catch from deploy-time to PR-time. Drops `check-mdx.ts`, the `check:content` script, and the `@mdx-js/mdx` devDep (only used by the script — the app uses `@mdx-js/rollup`). Co-Authored-By: Claude <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
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.
Oppsummering
Flytter alt dokumentasjonsinnhold fra Sanity inn i
apps/docs/src/content/som MDX-filer, slik at docs kan skrives, reviewes og merges i samme PR som koden. Løser AB#140852 under epicen Fase ut Sanity for Grunnmuren-dokumentasjonen (AB#140851).Hvorfor
react-liveimporterer@obosbbl/grunnmuren-react), så vi kan dokumentere ureleasede komponenter allerede før første npm-release.componentState: unreleasedskjuler dem fra meny/oversikt, ogci:versionflipper tilbeta/newautomatisk ved release.build:storybookbygger inn i samme docs-deploy, så en ny story shippes i samme PR som koden og MDX-en. Ingen «deploy story first»-friksjon..mdx-filer, havner alle klasser i CSS-bundlen naturlig.Hvordan
@mdx-js/rollup+remark-gfm+ frontmatter. To egne remark-plugins:```tsx live/```tsx) gjøres om tilComponentPreview(live, react-live) ellerCode(statisk, react-shiki) ved build..webp–.svgkun. To uavhengige mekanismer:apps/docs/migration/sanity-to-mdx.tsencoder hvert bilde først på WebP-kvalitet 80, og re-encoder samme bilde på 72 → 64 → 56 → 48 til det enkelte bildet er ≤ 250 KB. Nye bilder lagt til manuelt etter migreringen pre-optimaliseres av utvikleren (cwebp/Squoosh — se CONTRIBUTING).pnpm lint:imagessjekker hvert committet bilde og feiler hvis noen bryter en maksgrense. Trinnet er gated av et eget paths-filter-steg som detekterer hvilke filer som er endret i pushen/PR-en — selve lint-trinnet kjører bare når innholdsbilder eller lint-scriptet er blant endringene, ellers hoppes det over.componentState: unreleasedskjuler siden fra meny/oversikt, men URL-en virker. Ved release flipperscripts/strip-unreleased.ts(hektet ici:version) tilbeta(hvis noenpropsComponentsharUNSAFE_-prefiks) ellernew— så Version Packages-PR-en bærer både versjons-bumpen og synligheten i samme commit.Avhengigheter - oversikt
apps/docs/package.jsonsharpsom hører til migreringsscriptet)Sluttbalansen: -5 deklarerte deps, men vi bytter ut 14 tunge Sanity-pakker (selve
sanitymed studio,@sanity/visual-editing,@sanity/assist,styled-components,@portabletext/react, m.fl.) med 9 små build-time-plugins (remark-plugins,@mdx-js/rollup,image-size).Sanity-deps som fjernes (14):
sanity,@sanity/client,@sanity/vision,@sanity/visual-editing,@sanity/preview-url-secret,@sanity/image-url,@sanity/asset-utils,@sanity/code-input,@sanity/assist,@sanity/table,@portabletext/react,groq,styled-components,@code-obos/sanity-auth.MDX/build-deps som blir værende (9):
@mdx-js/rollup,remark-frontmatter,remark-gfm,remark-mdx-frontmatter,mdast-util-to-string,unist-util-visit,@types/unist,estree-util-value-to-estree,image-size.Kode som er viktig å se på
apps/docs/vite.config.ts— kobler MDX-støtten inn i Vite. Må kjøres før React-pluginet, ellers vil React ikke kjenne igjen den ferdig kompilerte MDX-en.apps/docs/src/lib/mdx/remark-code-blocks.ts— sørger for at kodeblokker i MDX-en (de som starter med```tsx) vises somComponentPreviewellerCodei ferdig dokumentasjon. Gjør at man kan skrive eksempler som vanlige kodeblokker i stedet for å pakke koden inn som en streng-verdi på en komponent — det siste hadde betydd at man måtte skrive om alle anførselstegn og spesialtegn for hvert eneste eksempel.apps/docs/src/lib/mdx/remark-headings.ts— gir hver overskrift en id som innholdsfortegnelsen kan lenke til, og lager samtidig selve listen over overskrifter. Det skjer i samme gjennomgang av siden, så lenkene i innholdsfortegnelsen og id-ene i teksten kan ikke komme i utakt.apps/docs/src/lib/content.ts— oversikten over alle migrerte MDX-filer. Hver rute slår opp her for å finne riktig side. Alle filer lastes inn samtidig ved build for å holde rute-koden enkel; vi kan dele dem opp senere hvis nedlastingen blir for tung.apps/docs/src/ui/mdx-doc.tsx— selve rammen rundt en docs-side (h1-tittel, ressurs-lenker, innholdsfortegnelse, status-alertbox inkl.unreleased, props-tabeller). Det er det som vises rundt selve teksten på siden.apps/docs/src/routes/_docs/$slug.tsx+komponenter/$slug.tsx— det som bestemmer hva som vises når noen besøker en docs-URL: prøver først å finne siden som en migrert MDX-fil, faller tilbake til Sanity hvis den ikke (enda) ligger i repoet.apps/docs/src/ui/main-nav.tsx+komponenter/index.tsx— venstremenyen og komponentoversikten skjuler sider som er merketcomponentState: unreleased.apps/docs/scripts/lint-images.ts— selve bilde-sjekken (kontrollerer format, filstørrelse og bredde).apps/docs/scripts/strip-unreleased.ts— kjøres når vi lager en ny release og endrercomponentState: unreleasedtilbetaellernewi hver MDX-fil. Det gjør at en ny komponent dukker opp i menyen samme dag som den publiseres på npm. Hektet inn i rootci:version(det changesets kaller for å lage Version Packages-PR-en)..github/workflows/main.yml— CI-trinnene som kjørervite buildav docs-appen (fanger MDX-feil og andre build-regresjoner før merge —cd.ymlbygger først ved deploy, som ville vært for sent) oglint:images.apps/docs/AGENTS.md+apps/docs/CONTRIBUTING.md— konvensjoner for både agenter og mennesker som skriver eller endrer docs.Kode som ikke trenger samme detaljgransking
apps/docs/migration/sanity-to-mdx.ts— migreringsscriptet. Brukes for å produsere innholdet, forsvinner med Sanity-integrasjonen i en oppfølger-PR.apps/docs/src/content/— alt er migrert fra Sanity. Hver fil er migrert med scriptet. Jeg har gått gjennom alle sider manuelt og det er kun små diffs på layout (spacing) og bilder (oppløsning/kvalitet).src/content/**/images/— alle lastet fra Sanity og optimalisert lokalt. 8.3 MB totalt, alle innenfor maksgrensene.Gjenstår (oppfølgere under epicen)
grunnmuren-datasettet i Sanity — siste steg, etter prod-verifisering./document-component-skill for å scaffolde nye komponentsider (er skissert og parkert lokalt hos meg).