Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 122 ยท Text Content

Code, Keyboard Input and Program Output

Mark up code snippets, keyboard shortcuts, program output and variables with code, pre, kbd, samp and var, and learn to escape < and & inside code samples.

Technical writing mixes ordinary sentences with several kinds of computer text: a function name, a command to type, a keyboard shortcut, an error message the program prints back. To a reader they all look "technical", but they are different things, and HTML has a separate element for each.

In this lesson you will learn <code>, <pre>, <kbd>, <samp> and <var>, how to combine them, and the one rule that trips up almost everyone the first time: how to show HTML tags inside a code sample without the browser treating them as real tags.

Inline code: <code>

<code> marks a fragment of computer code: an element name, a function, a file name, a CSS property, a short command. Browsers display it in a monospaced font, where every character has the same width.

HTML
<p>Call <code>toUpperCase()</code> to convert a string to capitals.</p>
<p>The settings live in <code>config/app.php</code>.</p>

That is all there is to it. Use <code> wherever you would switch to a "code font" in a printed manual.

Code blocks: <pre> + <code>

For a block of code with several lines, whitespace matters: line breaks and indentation are part of the code. Normal HTML collapses whitespace, so on its own <code> would squash your program onto one line. The fix is to wrap it in <pre> (preformatted text), which keeps every space and line break as written.

The standard pattern is <pre> on the outside for the formatting, and <code> on the inside for the meaning:

A code block

A few details from that example are worth knowing:

  • Indentation is literal. Inside <pre>, every space counts, so start the code at the left edge of your file, even if the surrounding HTML is indented. Otherwise the extra spaces appear on the page.
  • One newline is free. A line break directly after the <pre> opening tag is ignored, so you can start the code on the next line if you prefer. Any further blank lines are kept.
  • Long lines overflow. Code does not wrap. overflow-x: auto adds a horizontal scroll bar instead of letting the code spill out of its box. If you would rather wrap, use white-space: pre-wrap.
  • class="language-js" is a common convention (not a rule of HTML) that tells syntax-highlighting libraries which language the code is in.

Keyboard input: <kbd>

<kbd> marks input the user enters โ€” most often keys on a keyboard, but it can also be voice commands or text the user should type.

For a key combination, nest one <kbd> per key inside an outer <kbd> that represents the whole shortcut:

HTML
<p>Save the file with
  <kbd><kbd>Ctrl</kbd> + <kbd>S</kbd></kbd>.
</p>

For text the user should type, a single <kbd> is enough:

HTML
<p>In the search box, type <kbd>weather tomorrow</kbd> and press <kbd>Enter</kbd>.</p>

Browsers show <kbd> in a monospaced font, but a little CSS can turn it into realistic key caps, as you will see below.

Program output: <samp>

<samp> marks sample output from a program: an error message, a status line, the text a command prints in the terminal.

HTML
<p>If the disk is full, you will see <samp>Error: no space left on device</samp>.</p>

Combining <kbd> and <samp>

The two elements can be nested to say precisely what happened:

  • <kbd> inside <samp> โ€” input that the system echoed back, such as a command shown in a terminal transcript.
  • <samp> inside <kbd> โ€” the user chose something the screen displayed, such as a menu item or a button label.
kbd and samp together

The kbd kbd CSS selector styles only the inner keys, so the outer shortcut wrapper stays plain. In the terminal transcript, the whole session is output (<samp>), and the part the user typed is marked with <kbd> inside it.

Variables: <var>

<var> marks a variable: in mathematics, in programming, or a placeholder the reader should replace with their own value. Browsers show it in italics.

HTML
<p>The area of a rectangle is <var>width</var> ร— <var>height</var>.</p>

<p>Run <code>git clone <var>repository-url</var></code> to copy a project.</p>

The second example shows a placeholder inside a command: the reader types git clone, but replaces repository-url with a real address. Do not use <var> for every name in a code sample โ€” only where the variable is the point.

Showing HTML inside HTML: escaping

Here is the trap. Suppose you want to teach someone the <strong> element, and you write:

HTML
<p>Use the <code><strong></code> element for warnings.</p>

The browser does not know you meant it as an example. It sees a real <strong> start tag and makes the rest of the paragraph bold โ€” and the tag itself disappears. Putting it inside <code> or <pre> does not help; those elements change the font, not the parsing.

The fix is to escape the characters that HTML treats as special. Write &lt; (less than) instead of <, and &amp; (ampersand) instead of &:

Escaping a code sample

The broken version renders the tags instead of showing them; the escaped version shows exactly the characters you wanted. A few rules of thumb:

  • Always escape < as &lt; and & as &amp; in code samples.
  • Escaping > as &gt; is optional in normal text, but many people do it for symmetry.
  • Escape before you paste. Code editors and many online tools can do it for you, and when you insert text from JavaScript, textContent escapes automatically (more in The Document Object Model).

You will meet &lt;, &amp; and their many relatives properly in the next lesson, HTML Entities.

Need a bigger picture? A code sample with a caption is a great fit for <figure> and <figcaption> โ€” see Figures and Captions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which markup is best for a block of JavaScript code with indentation?

    <pre> preserves whitespace and line breaks, and <code> says the content is computer code.
  2. 2. How should you mark up the keyboard shortcut Ctrl + Shift + P?

    Each key is keyboard input, so it gets its own <kbd>, and an outer <kbd> groups the whole combination.
  3. 3. You write <code><em></code> to show the em tag. What happens?

    <code> does not stop HTML parsing. To show the tag as text, write &lt;em&gt;.
  4. 4. Which element marks an error message printed by a program?

    <samp> is for sample output from a program. <kbd> is user input and <var> is a variable.

Summary

  • <code> marks inline code; wrap multi-line code in <pre><code> to keep whitespace.
  • Inside <pre>, indentation is literal โ€” start code at the left edge, and use overflow-x: auto for long lines.
  • <kbd> is user input; nest <kbd> elements for key combinations.
  • <samp> is program output; combine it with <kbd> for echoed input or on-screen menu choices.
  • <var> marks variables and placeholders.
  • In code samples, always escape < as &lt; and & as &amp;.

Next: HTML Entities โ€” the full story of &lt;, &amp; and friends.