Showing code

How do I show code inside a sentence?

Wrap the fragment in code. The element marks a piece of computer code: an element name, a file name, a function, a CSS property, a shell command, a JSON key. Browsers render it in the default monospace font, which is why it often looks a little smaller than the surrounding text.

The code element is phrasing content, so it sits inside a paragraph, a list item or a table cell. Whitespace collapses as normal inside it, which is fine for short fragments. For anything with meaningful line breaks or indentation, use a block, covered next.

<p>Set the <code>lang</code> attribute on <code>&lt;html&gt;</code>,
then run <code>npm run build</code>.</p>

How do I show a multi-line code block?

Combine pre and code. The pre element keeps every space, tab and line break exactly as written. The code element says the content is code. Syntax highlighters such as Prism and highlight.js and most documentation generators look for this exact pattern.

Name the language with a class like language-css on the code element. HTML has no attribute for this; the class is a convention from the CommonMark spec that the tools follow.

One gotcha: the parser drops a single newline that comes right after the opening <pre> tag, but everything else counts. Indenting your HTML source pushes spaces into the rendered block, so start the code flush left even when the surrounding markup is indented.

<pre><code class="language-css">.card {
  padding: 1rem;
  border-radius: 8px;
}</code></pre>

Why does my HTML example disappear on the page?

The browser parses it as real markup. Inside code and pre, tags are still tags. If you write <p> inside a code block, the browser creates a paragraph element and shows nothing. Write <script> and the browser may try to run it.

Escape the characters that start markup. Write < for < and & for &. The > character is safe in text, but writing > keeps examples symmetrical. Inside attribute values, escape the delimiting quote as ".

If your content comes from a database or a CMS, escape it on the server or use textContent in JavaScript. Setting innerHTML with unescaped code samples is both a display bug and an injection risk.

• < becomes <
• > becomes >
• & becomes &
• " becomes " inside double-quoted attributes

What do kbd, samp and var mean?

The kbd element marks user input: keys on a keyboard, text the user types, menu choices or voice commands. The samp element marks sample output from a program, such as an error message or a line printed to a terminal. The var element marks a variable, either a placeholder in code or a symbol in maths.

Browsers default kbd and samp to monospace and var to italic. Pick by role, not by the look. A command the reader should type is kbd. The text the command prints is samp. The word that the reader should replace with their own value, like a file name, is var.

<p>Type <kbd>npm start</kbd> and you should see
<samp>Server running on port 3000</samp>.</p>
<p>Run <code>git checkout <var>branch-name</var></code>.</p>

Can these elements be combined?

Yes, and nesting is how you describe richer content honestly. A key combination is one kbd holding a kbd for each key: <kbd><kbd>Ctrl</kbd>+<kbd>S</kbd></kbd>. A menu path can nest samp inside kbd to say the user picks on-screen labels: <kbd><samp>File</samp> > <samp>Save</samp></kbd>.

A terminal transcript works well as a pre holding a samp for the whole session, with kbd around the lines the user typed. That keeps the prompt and the output distinct for styling and for any tool that reads the markup.

Screen readers do not announce any of these elements by default. The structure helps styling, search and copy tools; the words still need to make sense read aloud.

<pre><samp>$ <kbd>python3 --version</kbd>
Python 3.13.1</samp></pre>

How should long code blocks behave on a phone?

A pre block does not wrap lines, so a long line pushes the page wider than the screen and the whole layout scrolls sideways. Give code blocks their own scroll area with overflow-x: auto so only the block scrolls.

A block that scrolls must be reachable by keyboard, or keyboard users cannot read the hidden part. Add tabindex="0" to the pre and, if there are several blocks, an aria-label such as "CSS example" so the focus stop has a name. Chrome now makes scroll containers focusable automatically, but other browsers do not yet, so keep the attribute.

Wrapping with white-space: pre-wrap is the other option. It suits prose-like content such as log lines. It is a poor fit for Python or YAML, where a wrapped line looks like a new indented line and changes how the reader understands it.

pre {
  overflow-x: auto;
  tab-size: 2;
}

<pre tabindex="0" aria-label="Install command"><code>...</code></pre>

How do I keep code accessible and copyable?

Syntax highlighting splits code into dozens of span elements. That is fine for copy and paste, since the text is unchanged. Check that the colours meet a 4.5:1 contrast ratio against the background, both in light and dark themes, because highlight themes often use pale greys for comments.

Copy buttons should use the Clipboard API, navigator.clipboard.writeText(), on a real button with a visible label or an accessible name like "Copy code". Announce success with a short status message, for example in an element with role="status", so screen reader users know the copy worked.

Avoid putting code inside images. Readers cannot copy it, search engines cannot index it, and screen readers read the alt text at best.

How do I check code markup in DevTools?

Inspect a code block and look for the escaped characters. In the Elements panel, an example that shows <p> should appear as text, with no child element. If you see a real p node nested inside code, the source was not escaped.

Resize the viewport to 320px wide in the device toolbar and scroll the page. If the page scrolls sideways, a pre is too wide. Then press Tab through the page: each scrolling code block should get a visible focus ring, and arrow keys should scroll it.

What do AI tools commonly get wrong with code samples?

Generated tutorials often use code for every technical-looking word, including product names like GitHub that are not code. Keep code for things you could type into a file or a terminal.

Other common slips: pre without code, which loses the language class hook; unescaped < in examples, which silently swallows tags; kbd used for any monospace text, including output; and code blocks indented to match the template, which adds stray leading spaces to every line. Copy one generated example into a fresh file and run it. If it fails, the escaping or whitespace is wrong.

Field notes

• Use code for short bits of computer code inside a sentence.
• Combine pre and code to show a block that keeps its spacing.
• Escape < as < so example tags show as text.
• Use kbd for keys and typed input, and samp for program output.

Easy to get wrong

Unescaped tags are parsed as real elements, so the example vanishes.

Wrap code in code inside pre, and watch indentation, because pre keeps every leading space.

A key the user presses is input, which is kbd, not code.

A bare & can start an entity by accident. Escaping it is always safe.

Questions people ask

How do I display HTML tags as text on a web page?

Escape them: write &lt; for < and &gt; for >, for example &lt;div&gt;. The browser shows the characters instead of creating an element.

What is the difference between code and pre?

code marks content as computer code. pre preserves whitespace and line breaks. Use them together for code blocks.

Does HTML have syntax highlighting?

No. Highlighting comes from CSS, usually generated by a library or a build step that wraps tokens in spans.

Is the xmp tag still usable?

No. xmp is obsolete. Use pre and code with escaped characters.