Code Blocks
Code blocks display formatted code snippets, configuration examples, and technical output. They use a monospace font, syntax-appropriate formatting, and an optional copy button for easy reuse.
Use code blocks inside Prose content to present API examples, configuration snippets, file paths, and technical output that readers may need to copy or reference exactly as shown.
When to use
- Showing API request/response examples, configuration files, or command-line instructions — Any content where the reader needs to see exact syntax and may copy it directly.
- Presenting file paths, database queries, or technical identifiers that must be reproduced exactly — Monospace formatting and container styling signal "use this verbatim."
- Displaying sample data formats (JSON, XML, CSV) that accompany technical documentation — Structured data is easier to scan in a code block than in running prose.
- Any content where exact characters, spacing, and formatting matter — Code blocks preserve whitespace and prevent line-wrapping by default, keeping the structure intact.
Examples
Best practices
Always specify the language for fenced code blocks
It enables syntax formatting and helps screen readers announce the content type.
Use generic unstyled code blocks when the language is known
Without a language class, the block loses syntax formatting and assistive technology cannot describe what kind of code it contains.
Keep code blocks focused
Show the minimum needed to illustrate the point. Highlight the relevant lines, not the entire file.
Paste entire files into a code block
Readers lose the relevant lines in noise. Extract only the portion that matters and link to the full source if needed.
Use inline code for short references within sentences
File names, function names, property values, and similar fragments stay in the reading flow as inline <code> elements.
Use a full code block for a single value or file path
Inline code keeps short references in context. A full block for one value disrupts reading and wastes vertical space.
Interaction behavior
- The copy button appears when the reader hovers over or focuses on the code block. Clicking it copies the block's content to the clipboard.
- After copying, the button briefly shows a "Copied" confirmation before reverting to its default state.
- Code blocks that overflow horizontally become keyboard-scrollable — readers can Tab to the block and scroll with arrow keys.
- For long lines that should not scroll, the word-wrap option (
prose-pre-wrap) breaks lines to fit the container width.
Accessibility
- Code blocks that overflow horizontally are keyboard-scrollable — readers can navigate them without a mouse.
- The copy button includes an accessible label so screen readers announce its purpose. After activation, the "Copied" state is announced to assistive technology.
- Inline code is styled differently from surrounding text (monospace font, background tint) so readers can distinguish code from prose visually.