Author Event History walkthrough content in MDX, consolidate demo components - #5275
Merged
Conversation
…ponents The Event History walkthrough demos (docs/encyclopedia/event-history/*.mdx) were registered strip-block in the MDX -> Markdown pipeline, so the LLM/crawler markdown output (the .md files behind "Copy for LLM" and llms.txt) had zero content for these sections: no code sample, no step narrative, nothing. The underlying content also lived in JS data files (steps-*.js, languages/*.js), not in the .mdx pages themselves, so a docs writer editing a page couldn't see or change it. Both are fixed by authoring the walkthrough content directly in each .mdx page: a real fenced code block followed by one <WalkthroughStep> per step (with <WalkthroughCommand>/<WalkthroughEvent> for its Command/Event ledger entries), modeled on the existing SetupSteps/SetupStep pattern. The four previously separate demo components (CodeToCommandsDemo, CommandsToEventsDemo, HistoryReplayDemo, NonDeterminismDemo) collapse into one WalkthroughDemo, parameterized by ariaLabel/commandsLabel/eventsLabel props, since they only ever differed in those three values. - scripts/mdx-to-md.mjs + scripts/component-handlers/event-history-walkthrough.mjs: new transformer states render each step to a `#### Step N` heading with its Command/Event ledger, instead of stripping the whole block. - src/components/Demos/EventHistoryWalkthrough/: WalkthroughStep/ WalkthroughCommand/WalkthroughEvent are declarative marker components (never rendered); parseWalkthroughChildren reads them off the MDX-authored children. Deleted the now-dead steps-*.js/languages/*.js data files. - src/components/utils/extractElementText.js: fence-text extraction factored out of AnnotatedCode so both components share one implementation. Content itself is unchanged from what already shipped (steps, code samples, notes, per-SDK wording all preserved verbatim) -- this only moves where it lives and fixes how it round-trips through the markdown pipeline.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Duncanma
marked this pull request as ready for review
September 9, 2026 00:10
lennessyy
approved these changes
Sep 9, 2026
flippedcoder
approved these changes
Sep 9, 2026
Duncanma
enabled auto-merge (squash)
September 9, 2026 16:49
3 tasks
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
3 participants
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.
What does this PR do?
Moves the Event History walkthrough content (
docs/encyclopedia/event-history/*.mdx) from JS data files into the MDX pages themselves, and consolidates four separate demo components into one.Why:
CodeToCommandsDemo,CommandsToEventsDemo,HistoryReplayDemo,NonDeterminismDemo) were registeredstrip-blockin the MDX → Markdown pipeline, so the generated.mdoutput (behind "Copy for LLM",llms.txt, and any crawler fetching<page>.md) had zero content for these sections — no code sample, no step narrative, nothing.steps-*.js/languages/*.jsdata files, not in the.mdxpages, so a docs writer editing a page couldn't see or change it.What changed:
.mdxpage: a real fenced code block followed by one<WalkthroughStep>per step (with<WalkthroughCommand>/<WalkthroughEvent>for its Command/Event ledger entries).<WalkthroughDemo ariaLabel="..." commandsLabel="..." eventsLabel="...">— they only ever differed in those three values.scripts/mdx-to-md.mjs+scripts/component-handlers/event-history-walkthrough.mjsrender each step to a#### Step Nheading with its Command/Event ledger in the generated Markdown, instead of stripping the block.steps-*.js/languages/*.js/numbered.jsdata files.Compare before/after:
Notes to reviewers
Opened as draft; happy to mark ready whenever.
Test plan:
node tests/run-all.mjs— 127/127 passed (12 new tests covering the transformer's new states)yarn build— succeeds, no new transform warnings vs. main.mdoutput directly and confirmed all four walkthroughs now render real content (code + every step + ledger) instead of being emptyvale --config .vale-ci.ini docs/encyclopedia/event-history/— 0 errors/warnings (3 pre-existing suggestion-level heading-case findings, on headings this PR doesn't touch)git diffhas zero new[text](url)lines), so this doesn't changeyarn check-linksresultsNo content changes beyond relocation — every step's title, note, bullets, and Command/Event details are byte-for-byte what's live today (generated from the deleted JS files via a one-off script, not hand-retyped, to avoid transcription drift).