temporalio / temporalio/documentation

Quickstart pages (SetupSteps/CodeSnippet) don't use Snipsync for code samples

Open
#5,105 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.