Add Shiki syntax highlighting to code-bearing pages

[kentcdodds]

Intent

Make code on Kody pages actually readable. Guides, blog posts, community READMEs, onboarding MCP snippets, and a few account JSON dumps currently render as unstyled monospace. This adds syntax highlighting that follows the site theme without weakening the markdown safety model.

Summary

I looked at Shiki and think it is the right fit:

• VS Code-quality TextMate highlighting
• Dual light/dark themes via CSS variables, which maps cleanly onto :root[data-theme]
• Fine-grained ESM core that can run on Cloudflare Workers if we avoid Oniguruma WASM
• Token APIs so we can render JSX text + inline styles instead of innerHTML

What we did not want: Prism/Highlight.js (weaker grammars), shipping the full shiki entry (huge), or injecting highlighted HTML strings into untrusted README rendering.

Implementation:

• Fine-grained sync highlighter (createHighlighterCoreSync + JavaScript regex engine)
• GitHub light/dark dual themes
• Explicit language set; js/javascript/jsx alias onto TS/TSX grammars to avoid a second near-identical pair
• Wired into markdown fences (guides, blog, community READMEs), copyable guide blocks, onboarding config snippets, and job/activity JSON dumps
• Unknown langs / oversized snippets fall back to escaped plaintext
• ADR 0009 plus request-lifecycle docs

Testing

• Focused node tests: highlighter + markdown + SSR render
• npm run validate: typecheck, test (1888), e2e, mcp, docs, primitives, migrations, deploy-guardrails, backup/status builds passed
• First validate failed on lint (tabIndex on <pre>) and oxfmt; fixed. Re-ran oxfmt --check (clean) and oxlint on the changed files
• Manual: local dev server, SSR HTML contains class="shiki" + --shiki-dark token styles on /guides/package-authoring and the secrets blog post; UI walkthrough covers guide / blog / onboarding in light and dark

System changes

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ bff17d4e · Head: bad8f9a4

Classification: extends — app-ui now highlights code-bearing surfaces with a Worker-safe Shiki singleton; markdown safety still escapes via JSX.

Primitives touched

Primitive	Group	Impact
app-ui	surfaces	extends — Shiki highlighting on markdown, onboarding snippets, JSON dumps

System map

Markdown and snippet UIs call a shared highlighter; dual-theme CSS follows the existing theme toggle.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	appUi["app-ui<br/>Browser app"]:::extended
	appUi -->|"markdown fences + copy blocks"| appUi
	appUi -->|"onboarding MCP snippets"| appUi
	appUi -->|"jobs/activity JSON dumps"| appUi
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

flowchart TD
	md["marked lexer code token"] --> hl["renderHighlightedCode"]
	snip["onboarding / JSON dumps"] --> hl
	hl --> tokens["Shiki dual-theme tokens"]
	tokens --> jsx["JSX text + inline styles"]
	jsx --> css["styles.css data-theme / prefers-color-scheme"]

Loading

Before / after

Before: <pre><code>const x = 1</code></pre> with no token colors.

After: <pre class="shiki …" style="…--shiki-dark…"><code><span class="line">…</span></code></pre> with light colors inline and dark colors on CSS variables.

Invariants

Untrusted README rendering still never uses marked's HTML renderer or innerHTML. Highlight tokens are escaped JSX text.

  

Summary by CodeRabbit

• New Features

  • Added syntax highlighting for Markdown code blocks, configuration snippets, account activity metadata, and job parameters.
  • Supports light and dark themes, common languages, copied code blocks, and safe fallback for unsupported or oversized snippets.
  • Added highlighted JSON, TOML, shell, JavaScript, and JSX rendering where applicable.

• Documentation

  • Documented syntax-highlighting behavior, supported formats, theme handling, and implementation decisions.

• Tests

  • Added coverage for themes, token rendering, escaping, language aliases, and fallback behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b8f61613-cf64-4641-b9dd-162bc5aab2f4

📥 Commits

Reviewing files that changed from the base of the PR and between bff17d4 and bad8f9a.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (14)

• docs/contributing/architecture/index.md
• docs/contributing/architecture/request-lifecycle.md
• docs/contributing/decisions/0009-shiki-syntax-highlighting.md
• docs/contributing/decisions/index.md
• packages/worker/client/copy-code-block.tsx
• packages/worker/client/markdown-view.node.test.ts
• packages/worker/client/markdown-view.tsx
• packages/worker/client/routes/account-activity.tsx
• packages/worker/client/routes/account-jobs.tsx
• packages/worker/client/routes/onboarding-mcp-client-tabs.tsx
• packages/worker/client/syntax-highlight.node.test.ts
• packages/worker/client/syntax-highlight.tsx
• packages/worker/package.json
• packages/worker/public/styles.css

---

📝 Walkthrough

Walkthrough

Changes

Syntax highlighting

Layer / File(s)	Summary
Shiki highlighter foundation packages/worker/client/syntax-highlight.tsx, packages/worker/client/syntax-highlight.node.test.ts, packages/worker/package.json	Added synchronous Shiki highlighting with supported languages, aliases, dual themes, JSX token rendering, size limits, and plaintext fallback.
Markdown and copyable code rendering packages/worker/client/markdown-view.tsx, packages/worker/client/copy-code-block.tsx, packages/worker/client/markdown-view.node.test.ts	Markdown and copyable code blocks now render highlighted code and pass language metadata.
Route snippet integrations packages/worker/client/routes/account-activity.tsx, packages/worker/client/routes/account-jobs.tsx, packages/worker/client/routes/onboarding-mcp-client-tabs.tsx	Account metadata, job parameters, and onboarding snippets now render highlighted JSON, TOML, and shell content.
Theme styling and architecture records packages/worker/public/styles.css, docs/contributing/architecture/*, docs/contributing/decisions/*	Added Shiki dark-theme styling and documented the syntax-highlighting architecture in ADR 0009.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MarkdownView
  participant CopyCodeBlock
  participant renderHighlightedCode
  participant Shiki
  participant ThemeCSS
  MarkdownView->>renderHighlightedCode: render fenced code with language
  MarkdownView->>CopyCodeBlock: pass code and language for copyable blocks
  CopyCodeBlock->>renderHighlightedCode: render highlighted content
  renderHighlightedCode->>Shiki: tokenize supported code with light and dark themes
  Shiki-->>renderHighlightedCode: return JSX token output and theme styles
  ThemeCSS->>renderHighlightedCode: apply dark-theme token variables

Loading

Possibly related PRs

• kentcdodds/kody#1108: Both changes update the ADR index.
• kentcdodds/kody#1233: Both changes modify markdown rendering.
• kentcdodds/kody#1255: Both changes modify copyable code block rendering.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding Shiki syntax highlighting to code-bearing pages.
Description check	✅ Passed	The description includes the required Intent, Summary, Testing, and System changes sections with relevant implementation, validation, and risk details.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/syntax-highlighting-shiki-dc7f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}