Chapter 8 11 mins

Learning outcomes:

  1. Representing code (<code>)
  2. Showing code's sample output (<samp>)
  3. Showing keyboard input (<kbd>)


Presenting code blocks in HTML documents has become quite a common activity given that there are countless websites that ought to deal with showcasing code snippets.

Tech blogs, platforms teaching programming (such as this one), software documentations, API providers — there is a whole ton of places where being able to present code to the user is a vital requirement.

And not just code; we also need to showcase the output of the code when trying to replicate terminals windows and CLI applications using HTML.

In this chapter, we shall learn about two HTML elements to help us in this regard: <code> and <samp>. Following this, we'll learn about the <kbd> element, which although isn't precisely tied to code, gets rendered using a monospaced font and thus is explored right alongside these code-related HTML elements.

Code via <code>

To showcase computer code in an HTML document, we use the <code> element.

By default, since it represents code, browsers render the text inside a <code> element using a monospaced font.

Let's see what that is.

Monospaced font

If you don't know about it, a monospaced font is a font where every character is based on one single width, hence the name 'monospaced' ('mono' means one).

For instance, following is a non-monospaced font, Arial, where the width of each character is not the same:

Learning HTML
A non-monospaced, sans-serif font, Arial.

In contrast, here's the same text written using a monospaced font, Consolas:

Learning HTML
A monospaced font, Consolas.

Notice how the width of each character seems to be the same. Take a look at the letter 'i' here and compare it with the 'i' in Arial (shown above).

A monospaced font is a de facto font choice for displaying code since it leads to a much higher readability if compared to using any other kind of font to present code.

Let's now consider a quick example of <code>.

In the following code, we lay out a sentence stating a fact about variables in JavaScript, involving two keywords (which represent JavaScript code):

<p>In JavaScript, <code>var</code> and <code>let</code> both define variables.</p>

We mark up these keywords using the <code> element.

Following is the output produced:

In JavaScript, var and let both define variables.

Notice the words 'var' and 'let' above — they both are based on a different font than that of their surrounding text.

Keep in mind that <code> itself is NOT meant to display a whole block of code; instead, it's meant for presenting inline code, along with other text.

Likewise, the following isn't really desirable:

<p>Here's some JavaScript code:</p>

<code>var x = 10;
console.log(x ** 2);</code>

In fact, if we take a look at the output produced when using <code> alone, as follows:

Here's some JavaScript code:

var x = 10; console.log(x ** 2);

we see that new lines in the code text don't get rendered out on the document.

If we wish to denote a whole block of code appropriately, we should encapsulate <code> inside a <pre> element.

This is illustrated below:

<p>Here's some JavaScript code:</p>

<pre><code>var x = 10;
console.log(x ** 2);</code></pre>

Here's some JavaScript code:

var x = 10; console.log(x ** 2);

Thanks to <pre>, the new lines in the code get rendered correctly out on to the document.

Simple, yet perfect!

Sample output via <samp>

Let's say we have some code displayed on an HTML page and now wish to showcase the output text generated by that code. Which element should we use here?

Well, this is the job of <samp>.

The <samp> element stands for 'sample output' and is meant to represent the textual output generated by a computer program.

Akin to <code>, browsers render the text inside a <samp> element using a monospaced font as well, by default. This makes sense because when working with real code, its output is typically presented in terminal programs which also use a monospaced font for rendering.

And again just like <code>, <samp> on its own is used to denote inline output text. If we wish to represent a block of output, we guessed it...a <pre> element.

Time for an example.

Let's say we want to write out a sentence on an HTML document saying that a particular function call in Python produces a given output. Here's how we'd do so:

<p>The <code>print(11 ** 2)</code> function call in Python outputs <samp>121</samp>.</p>

The print(11 ** 2) function call in Python outputs 121.

The short code statement of Python is wrapped up inside the <code> element whereas the output produced by it, i.e. 121, is wrapped up inside the <samp> element.

In the example above, 121 doesn't represent code, and so it doesn't make sense at all to mark it up using the <code> element.

Reiterating on it (because it's such an important point), just like <code>, <samp> on its own should be inlined with other content; it should NOT be used to denote a whole block of output on its own.

So, for instance, the following isn't an ideal usage of <samp>:

<p>The code produces the following output:</p>

<samp>0 1 2

We have a block of output marked up using <samp> without anything wrapping up the element. Because <samp> isn't originally meant to represent blocks of output, this usage of <samp> isn't considered that good.

Here's the output produced:

The code produces the following output:

0 1 2 -1

We have the same issue we had above when we used the <code> element alone to represent a piece of code containing new lines.

That is, -1 appears on the same line as 0 1 2 despite the fact that it's on a new line in the source code. This happens because <samp> follows the typical whitespace behavior of elements in HTML, i.e. to reduce down a sequence of whitespace characters to a single space.

If we wish to denote a block of output text using <samp>, then we guessed it again...wrap the <samp> element inside a <pre> element.

Likewise, the code above should be rewritten as follows:

<p>The code produces the following output:</p>

<pre><samp>0 1 2

Here's the output this produces:

The code produces the following output:

0 1 2

So was this easy or not?

It is possible to get all <samp> elements in HTML to be preformatted by themselves, using the power of CSS, but that's not desirable when trying to produce a 'block' of sample output; for this, it's better to wrap <samp> with the <pre> element.

Keyboard input via <kbd>

Often times, we might want to mark up text that represents keyboard input. For this, we have the <kbd> element.

As a simple example, suppose we have a webpage explaining a program's graphical interface. The program might have some keybindings configured for different actions, like Ctrl and S to save a file.

To denote such keybindings on the webpage, we can use the <kbd> element.

Let's see a quick example:

<p>To save a file, we use <kbd>Ctrl + S</kbd>.</p>

To save a file, we use Ctrl + S.

As can be seen here, <kbd> elements also render their content using a monospaced font (which can obviously be changed using CSS).

Sometimes, besides denoting keybindings, <kbd> can also be used to showcase text input using a keyboard.

An example follows:

<p>To list all items in the current directory, enter <kbd>dir</kbd> in the terminal.</p>

To list all items in the current directory, enter dir in the terminal.

Here, 'dir' isn't really any code, nor any sample output, but rather some input that the user has to enter into the terminal, hence we denote it using the <kbd> element in lieu of using <code> and <samp>.

"I created Codeguage to save you from falling into the same learning conundrums that I fell into."

— Bilal Adnan, Founder of Codeguage