Code and UI elements

Technical documentation frequently references things that exist in the interface — buttons, menus, fields, settings — as well as code: commands, file names, variables, values. Formatting these elements consistently makes the documentation easier to follow and helps readers distinguish at a glance what is a UI element and what is something they type or see in a codebase.

Formatting UI Elements

Bold for UI element names

Use bold to refer to named interface elements — buttons, tabs, menus, settings panels, page names. Apply the exact capitalization shown in the interface.

For which verb to pair with each element type (Click vs. Select vs. Turn on vs. Drag, and so on), see the Choose Precise Verbs for UI Interactions section of the Verbs, Tense, and Mood guide. This article covers how the element name itself is formatted; that one covers which action verb belongs with it.

Navigation paths

When directing a reader through a sequence of UI locations, use a right angle bracket (>) to separate each step in the path. Bold all elements in the path.

Example: "Go to Settings > Account > Notifications."

This notation is compact, universally recognized in technical documentation, and clearly communicates a navigation sequence.

Referring to UI elements generically

When referring to a UI element type without naming a specific instance, do not bold or capitalize: "the dropdown menu," "the search bar," "the toggle," "the sidebar."

Formatting Code

For the general mechanics of code blocks — language tags, line length, and when to use inline formatting versus a full block — see the Code Blocks section of the Formatting Standards guide. This section covers the specific elements that get inline or block formatting, and the conventions unique to them.

Inline code

Use inline code formatting (monospace font) for any of the following that appear within running prose:

• Command names: run git status
• File names and paths: open config.json
• Variable names: set the value of timeout
• Parameter names: use the --force flag
• API endpoints: send a request to /api/v1/articles
• Code values and strings: set the field to true
• Environment variable names: set NODE_ENV
• HTTP status codes when referenced as literal values: the server returns 404
• Keyboard shortcuts when written as key names: press Ctrl+S

For where closing punctuation goes relative to an inline code span at the end of a sentence, see the Punctuation with Inline Code section of the Punctuation guide.

Code blocks

Use a code block (a distinct, full-width block in monospace font) for:

• Code samples of more than one line
• Command-line instructions the reader will copy and paste
• Configuration file examples
• Request and response examples for API documentation
• Any code that benefits from syntax highlighting

Always specify the programming language when your documentation platform supports syntax highlighting. This improves readability and helps readers recognize the context.

Example of a correctly formatted code block with language specified:

curl -X POST https://api.example.com/v1/articles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My article", "content": "Article body"}'

Placeholder values in code

When a code sample contains a value the reader must replace with their own, format it as a placeholder that is visually distinct from actual code values. Common conventions are:

• Uppercase with underscores: YOUR_API_KEY
• Angle brackets: <your-api-key>

Choose one style and apply it consistently. Always explain what the placeholder represents: "Replace YOUR_API_KEY with the API key from your account settings."

This is a separate convention from the square-bracket placeholders used in prose templates (for example, "This article explains how to [task] for [audience]," as described in the Brackets for Placeholders section of the Punctuation guide). Do not use square brackets for placeholders inside a code sample — in many languages, square brackets have real syntactic meaning (arrays, optional arguments), and using them as plain-English placeholder notation inside actual code risks being misread as literal syntax. Reserve square brackets for prose templates only, and use uppercase-with-underscores or angle brackets for placeholders that appear inside code.

Formatting Keyboard Shortcuts

Keyboard shortcuts that appear in prose use inline code formatting: "press Ctrl+S." When presenting a reference table of shortcuts, use a table with columns for the shortcut and the action it performs.

For cross-platform instructions, present both variants: "Press Ctrl+Z (Windows) or Cmd+Z (Mac) to undo."

Capitalize key names: Enter, Shift, Esc, Tab, Delete. Use a plus sign (+) to indicate key combinations, with no spaces around it: Ctrl+Alt+Delete.

Formatting File Types and Extensions

Refer to a file format generically in uppercase, following the acronym rule in the Capitalization guide: a PDF, a CSV, a JSON file.

An actual, literal file name is a different case — it's a case-sensitive code value, not a generic format reference, and should be reproduced exactly as it exists, in inline code formatting: export.csv, config.json. See the Code and Case-Sensitive Values section of the Capitalization guide for the full reasoning on why case-sensitive values are never adjusted to match surrounding prose capitalization.

Self-Audit Checklist

Before publishing, check UI and code formatting against these questions:

• Are all named UI elements bolded, with capitalization matching the interface exactly?
• Are navigation paths written with bolded elements separated by >?
• Are generic (unnamed) UI element types left unbolded and lowercase?
• Is inline code formatting used for all commands, file names, variables, parameters, endpoints, values, environment variables, and status codes mentioned in prose?
• Do all multi-line code samples use a full code block with a language tag specified?
• Is exactly one placeholder convention (uppercase-with-underscores or angle brackets) used consistently within code samples, distinct from square-bracket prose placeholders?
• Is every placeholder explained in the surrounding text?
• Are keyboard shortcuts in inline code formatting, with cross-platform variants shown where relevant?
• Are generic file format references capitalized as acronyms, while literal file names are reproduced exactly in code formatting?