Skip to content

Extract code snippets to separate files for maintainability#626

Open
m-ods wants to merge 17 commits intomainfrom
claude/extract-mdx-code-blocks-0ZRew
Open

Extract code snippets to separate files for maintainability#626
m-ods wants to merge 17 commits intomainfrom
claude/extract-mdx-code-blocks-0ZRew

Conversation

@m-ods
Copy link
Contributor

@m-ods m-ods commented Feb 10, 2026

Summary

This PR refactors inline code examples in documentation pages to use external snippet files, improving maintainability and reducing duplication across the codebase.

Key Changes

  • Extracted code snippets: Moved inline code blocks from auto-chapters.mdx and content-moderation.mdx to dedicated snippet files in fern/snippets/audio-intelligence/
  • Updated documentation: Replaced inline <code> blocks with <Code src="..."> component references that point to external snippet files
  • Added prettier ignore: Updated .prettierignore to exclude the fern/snippets/ directory from formatting
  • Preserved highlighting: Maintained line highlighting directives (e.g., highlight={[8]}) in the component references

Implementation Details

  • Code snippets are now organized by feature (e.g., auto-chapters/, content-moderation/) and language
  • Each snippet file is named descriptively (e.g., python-sdk.py, javascript.js, bash.sh)
  • The refactoring covers multiple languages: Python (SDK and REST), JavaScript (SDK and REST), C#, Ruby, and PHP
  • This change enables easier snippet reuse across multiple documentation pages and simplifies updates to code examples

Benefits

  • Single source of truth: Code examples are maintained in one place
  • Reduced duplication: Snippets can be referenced from multiple documentation pages
  • Easier maintenance: Updates to code examples only need to be made once
  • Better organization: Snippets are logically grouped by feature and language

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA

claude and others added 17 commits February 10, 2026 06:47
@claude
extract code snippets from audio-intelligence MDX files
1c4f372 
Extract inline code blocks from 8 MDX files into separate snippet files
under fern/snippets/audio-intelligence/. Code blocks with extractable
languages (python, javascript, csharp, ruby, php, bash) and >3 lines
are replaced with <Code src="..." /> components. JSON/text/plain output
blocks are preserved inline. Added fern/snippets/ to .prettierignore
since snippet files are code examples that may not be syntactically
valid for prettier.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from speech-understanding MDX files
56a3aff 
Extract inline code blocks from 3 MDX files (custom-formatting,
speech-understanding, translation) into separate snippet files under
fern/snippets/speech-understanding/. 26 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from lemur MDX files
244efda 
Extract inline code blocks from 5 MDX files into separate snippet files
under fern/snippets/lemur/. 73 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from llm-gateway MDX files
c219011 
Extract inline code blocks from 7 MDX files into separate snippet files
under fern/snippets/llm-gateway/. 27 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from getting-started MDX files
6b18275 
Extract inline code blocks from 3 MDX files into separate snippet files
under fern/snippets/getting-started/. 90 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from speech-to-text/pre-recorded-audio MDX files
68c0b85 
Extract inline code blocks from 19 MDX files into separate snippet files
under fern/snippets/speech-to-text/pre-recorded-audio/. 149 snippet
files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from speech-to-text/universal-streaming MDX files
eb62d29 
Extract inline code blocks from 10 MDX files into separate snippet files
under fern/snippets/speech-to-text/universal-streaming/. 35 snippet
files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from integrations MDX files
1165b0e 
Extract inline code blocks from 9 MDX files into separate snippet files
under fern/snippets/integrations/. 32 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from guides and cookbooks MDX files
2c7302b 
Extract inline code blocks from guides/ section including all cookbooks
subdirectories (core-transcription, streaming-stt, lemur,
audio-intelligence). 558 snippet files created across 79 MDX files.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from concepts MDX files
408742f 
Extract inline code blocks from 1 MDX file into separate snippet files
under fern/snippets/concepts/. 1 snippet file created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from use-cases MDX files
c7aa750 
Extract inline code blocks from 3 MDX files into separate snippet files
under fern/snippets/use-cases/. 54 snippet files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
extract code snippets from speech-to-text root MDX files
a2e3669 
Extract inline code blocks from 3 root-level speech-to-text MDX files
(livekit-intro-guide, pipecat-intro-guide, streaming). 42 snippet
files created.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
apply prettier formatting to faq and voice-agent script
aac2595 
Prettier reformatted these files during the format pass. No functional
changes - only whitespace/formatting adjustments.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
fix Code src paths to use relative paths and restore mangled tables
0c56951 
Fern resolves <Code src="..."> paths relative to the page file, not the
fern/ root. Change all paths from src="snippets/..." to use relative
paths like src="../../snippets/...".

Also restore markdown tables that were mangled when prettier reformatted
<Code> tags to multi-line, causing the following table to be treated as
prose text. Revert unrelated prettier changes to FAQ and voice-agent.js.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
fix remaining mangled tables, JSX comment escaping, and formatting
5105e6a 
- Restore mangled markdown tables in key-phrases.mdx, customize-parameters.mdx
  and translation.mdx from git history
- Fix {/\* escaped JSX comments to {/* in custom-formatting.mdx and
  translation.mdx (caused acorn parse errors in fern generate)
- Remove duplicate mangled table in translation.mdx
- Add missing blank line between Code tag and heading in translation.mdx
- Restore proper list formatting in medical-scribe-best-practices.mdx

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@claude
Fix customize-parameters.mdx: remove mangled duplicate table blocks
882c649 
Remove three mangled table duplicates that were left behind by the
table restoration script. These corrupted text blocks contained \_Legacy
which the MDX parser interpreted as markdown list items, breaking the
<Tab> structure.

https://claude.ai/code/session_01NinNALWi81ZHvgeZkVoziA
@m-ods @claude
fix CI failures: lint errors, formatting drift, and MDX parse errors (#…
745fd9e 
…622)

- Fix openapi.yml: change `objects` to `items` for expected_languages arrays
- Fix openapi-overrides.yml: add missing Authorization header, remove
  unexpected properties, add word-search example
- Remove commented-out JSX Tab sections in translation.mdx and
  custom-formatting.mdx that prettier escapes to `{/\*`, breaking acorn
- Apply prettier formatting to customize-parameters.mdx and voice-agent.js
- Regenerate fern definition and openapi.json

https://claude.ai/code/session_01NxTbqRLFJXHtJG11JMQVa2

Co-authored-by: Claude <noreply@anthropic.com>
@LeeVaughn LeeVaughn requested review from zakki-aai and removed request for zakki-aai February 10, 2026 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zakki-aai zakki-aai Awaiting requested review from zakki-aai

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@m-ods @claude