docs: add Syntax component for inline language-specific identifiers

[notowen333]

Description

Adds a new <Syntax> MDX component that renders language-appropriate identifiers (Python snake_case vs TypeScript camelCase) inline based on the global language selector. This eliminates the manual pattern of spelling out both variants in shared prose (e.g., `snake_name` / `camelName`).

Motivation

Documentation pages frequently reference SDK identifiers in prose that sits outside language-specific tabs. Previously this meant writing both names inline, which was verbose, inconsistent across pages, and didn't react to the reader's language preference. The new component provides a single source of truth per identifier that switches live with the language toggle.

Public API Changes

No public API changes — this is a documentation infrastructure addition.

Component API

<Syntax py="conversation_manager" ts="conversationManager" />
<Syntax py=".as_tool()" ts=".asTool()" />
<Syntax py="strict=True" ts="strict: true" code={false} />

Prop	Type	Default	Description
py	string	required	Python identifier
ts	string	required	TypeScript identifier
code	boolean	true	Wrap in <code> (false for plain text)

Implementation

• site/src/components/Syntax.astro — custom element <syntax-switch> with an idempotent inline script that reads the same localStorage key as the existing language tabs
• Auto-imported via astro-auto-import so no explicit imports needed in MDX
• Reacts to tab clicks (.lang-option delegated listener) and cross-tab storage events

Scope

• Converted ~26 instances across 16 documentation pages
• Updated agent skills (writer, reviewer, audit) to teach future authors about the component
• Updated references (mdx-authoring.md, voice-guide.md) and contributor docs

Type of Change

Documentation update

Testing

• Full npx astro build passes (655 pages, 0 broken links)
• Verified every TypeScript identifier against SDK source at sdk-typescript/strands-ts/src/
• Manual browser testing confirms live language switching

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Comment

Clean, well-scoped documentation addition. I spot-checked the converted identifiers against the SDK source (recordDirectToolCall, asTool, retryStrategy, structuredOutputSchema, ModelThrottledError, invocation_state) and they all match. The companion docs/skills updates do a good job teaching future authors when to reach for <Syntax> vs <Tabs>. One point worth discussing before merge (graceful degradation / SSR), plus a couple of minor cleanups.

Review themes

• Rendering / SEO (important): The component renders empty markup server-side and fills text only via JS, so no-JS readers and crawlers see a blank gap, with a brief empty-flash on first paint. The sibling LangCodeBlock already solves this by SSR-ing both variants and toggling with CSS — worth mirroring. (inline)
• Maintainability (suggestion): The localStorage key + default-language constants are now copied across four files; a shared module would prevent drift. (inline)
• Dead attribute (suggestion): data-code is set but never read. (inline)
• Verification: Identifier accuracy confirmed against source; textContent (not innerHTML) keeps it XSS-safe; the single-run init guard is fine given the site doesn't use Astro view transitions.

Nice quality-of-life improvement for the docs — the live language switching on inline identifiers is a real readability win.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• contribute/contributing/documentation
• user-guide/concepts/agents/agent-loop
• user-guide/concepts/agents/conversation-management
• user-guide/concepts/agents/hooks
• user-guide/concepts/agents/prompts
• user-guide/concepts/agents/retry-strategies
• user-guide/concepts/agents/snapshots
• user-guide/concepts/agents/state
• user-guide/concepts/agents/structured-output
• user-guide/concepts/context-management
• user-guide/concepts/model-providers/google
• user-guide/concepts/multi-agent/agents-as-tools
• user-guide/concepts/plugins/context-offloader
• user-guide/concepts/plugins
• user-guide/concepts/plugins/skills
• user-guide/concepts/tools
• user-guide/observability-evaluation/traces

Updated at: 2026-06-12T15:54:54.338Z

[github-actions]

Re-reviewed after 921bd6d (fix(syntax): server-render both variants, remove dead data-code attr). Both actionable items from the last pass are resolved:

• ✅ SSR/SEO/graceful degradation — Both variants now render server-side (<code data-lang="Python"> / <code data-lang="TypeScript">), with CSS hiding Python by default and JS toggling display. No-JS readers and crawlers now see the identifier, and the empty-content flash is gone. This matches the LangCodeBlock pattern cleanly.
• ✅ Dead data-code attribute — Removed.

The remaining note (extracting the duplicated STORAGE_KEY/DEFAULT_LANG into a shared module) was explicitly non-blocking, so deferring it is a reasonable call — though a follow-up would be nice given the key is now repeated in four places.

Updated assessment: Approve. Nice, quick turnaround. 👍