temporalio / temporalio/documentation
Quickstart pages (SetupSteps/CodeSnippet) don't use Snipsync for code samples
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 173
- Forks
- 330
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 156
Description
Summary
The SetupSteps/SetupStep/CodeSnippet component family (src/components/Quickstart/SetupSteps/SetupSteps.js), used by every "Quickstart" page across the site (the per-SDK Nexus quickstarts under docs/develop/*/nexus/quickstart.mdx, and the new Standalone Activities quickstarts added in #5081), hand-types code samples directly into the code={} prop instead of pulling them from the CI-tested sample repos via Snipsync.
AGENTS.md states a general preference: "Prefer code extracted from CI-enabled sample repos via Snipsync." Hand-typed code in these pages can silently drift out of sync with the real, compiled/tested samples in samples-go, samples-python, samples-java, samples-dotnet, samples-ruby, and samples-typescript — there's no CI check tying the docs' code to the sample repos for this component family, unlike the plain-Markdown Feature Guide pages, which do use Snipsync today.
Why Snipsync isn't wired up today
Snipsync's fmt() (src/Sync.js in the snipsync repo) always writes back a Markdown link line plus a fenced ```lang code block. That's valid in normal Markdown flow, but SetupStep's two-pane layout needs code passed as a JS template literal inside a JSX prop (code={<CodeSnippet>{...}</CodeSnippet>}), which needs raw code text, not a Markdown fence — dropping a fence in there would render as literal backticks, not a code block.
Possible path forward (unverified)
Snipsync supports per-snippet config to suppress both the source link and the fence ({"enable_source_link": false, "enable_code_block": false}), which would leave just raw code lines, plus an MDX-flavored marker variant ({/* SNIPSTART ... */} / {/* SNIPEND */}) already added to snipsync for JSX contexts. In theory, combining both inside the template literal could let Snipsync populate the code={} prop with real, CI-tested code. No page in the repo currently does this — it would need to be prototyped on a single snippet first to confirm MDX doesn't mishandle the marker text inside a backtick string before rolling it out further.
Scope
This affects the whole Quickstart template family, not any single page — worth tackling as its own change rather than folding into a content PR.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in src/components/Quickstart/SetupSteps/SetupSteps.js and inspect the Quickstart pages under docs/develop/*/nexus/quickstart.mdx, along with the Snipsync behavior described in the issue. Prototype one snippet using the stated raw-code configuration and MDX marker variant, verifying that the template literal renders correctly. Done means the component family can use CI-tested samples without Markdown fences and the approach is ready to apply across the affected quickstarts.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100