💻 Chapter 15: Code, Monospace & Preformatted Text

Displaying HTML Code within HTML

Escaping HTML syntax tokens, character entities, legacy tag traps, and extracting raw markup with the `<template>` API.

LEARNING OBJECTIVES ⌵

Understand why web browsers execute unescaped HTML tags placed inside <code> or <pre>.
Master mandatory HTML character entity conversions (<, >, &, ").
Recognize why historical elements like <xmp>, <plaintext>, and <listing> are obsolete and dangerous.
Utilize the HTML5 <template> element to safely store and extract raw HTML for interactive documentation playgrounds.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine writing a book in English that teaches Spanish grammar. When you want to discuss the Spanish word for "dog", you put it in quotes: "The word 'perro' means dog." You don't want the reader to think you are suddenly shouting Spanish orders at them; you are talking about the word as an object of study.

In HTML, the browser's parser is constantly looking for the < character. The moment the parser sees <p> or <button>, it assumes: "Aha! Time to construct a real DOM node and paint a button on the screen!"

If your goal is to teach someone how to write a button in HTML, you cannot simply type <button> into your HTML file, or the browser will build an active clickable button instead of displaying the source code. To make the browser display the code about HTML, you must escape the characters so the parser treats them as literal text glyphs.

Parser Trajectory:
1. Unescaped:   <code><button>Click Me</button></code>
   Parser sees '<' ---> Builds actual HTMLButtonElement in DOM! (Visual Button)

2. Escaped:     <code>&lt;button&gt;Click Me&lt;/button&gt;</code>
   Parser sees '&' ---> Converts to literal character '<' ---> Displays code text!

Technical Deep Dive & Specifications

The Mandatory Escaping Rules

To render HTML source code safely inside any HTML document (including inside <code> and <pre>), the following characters must be replaced with their respective character entity references:

Character	Literal Name	Entity Replacement	Numeric Entity	Why It Must Be Escaped
`<`	Less-Than / Open Angle	`<`	`<`	Prevents browser from treating text as an HTML tag opener.
`>`	Greater-Than / Close Angle	`>`	`>`	Prevents premature tag closure or syntax misinterpretation.
`&`	Ampersand	`&`	`&`	Prevents parser from mistaking standard text for a character entity.
`"`	Double Quote	`"`	`"`	Required when displaying HTML attributes inside attribute strings.

The Obsolete Historical Traps: `<xmp>`, `<plaintext>`, and `<listing>`

In early HTML (HTML 2.0 / 3.2), browsers introduced non-standard elements to display unescaped code:

<xmp> (Example): Rendered everything literally until an explicit </xmp> closing tag.
<plaintext>: Stopped HTML parsing entirely for the rest of the file (irreversible!).
<listing>: Legacy fixed-width listing container.

+--------------------------------------------------------------------------------+
| ⚠️ HISTORICAL WARNING: <xmp>, <plaintext>, and <listing> ARE OBSOLETE!         |
| Modern browsers either treat them as deprecated quirks-mode elements or drop   |
| support entirely. Never use them in modern production code.                    |
+--------------------------------------------------------------------------------+

Modern Dynamic HTML Extraction with `<template>`

When building an interactive component playground (like CodePen, Storybook, or documentation sites), escaping thousands of lines of HTML manually is tedious.

The modern HTML5 standard provides the <template> element. The contents of <template> are parsed by the browser into an inactive DocumentFragment (scripts do not run, images do not download, styles do not apply). You can extract its raw string with JavaScript:

<!-- Inactive inert template -->
<template id="demo-markup">
  <div class="user-profile">
    <img src="avatar.jpg" alt="Profile Picture">
    <h3>Alex Rivers</h3>
  </div>
</template>

<!-- Target display container -->
<pre><code id="code-viewer" class="language-html"></code></pre>

<script>
  const template = document.getElementById("demo-markup");
  const codeViewer = document.getElementById("code-viewer");
  
  // .innerHTML returns the raw HTML string, which .textContent safely escapes!
  codeViewer.textContent = template.innerHTML.trim();
</script>

+-------------------------------------------------------------------------------+
| <template> (Inert DOM)                                                        |
|   |                                                                           |
|   |-- .innerHTML ---> Raw String: '<div class="user-profile">...'              |
|                             |                                                 |
|                             v                                                 |
|   +-------------------------------------------------------------------------+ |
|   | codeViewer.textContent = string (Auto-escapes all '<' and '>' entities) | |
|   +-------------------------------------------------------------------------+ |
|                             |                                                 |
|                             v                                                 |
|   Displays beautifully formatted, safe HTML code on the webpage!              |
+-------------------------------------------------------------------------------+

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL example.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 49–55: The live UI component is rendered directly inside the .preview-box. The browser parses <article>, <h3>, and <button> into live interactive elements.
Line 61–66: Inside <pre><code>, every < is replaced with < and every > is replaced with >.
Line 61–65: Span elements with classes (tag, attr, val) apply custom syntax token colors to the escaped HTML markup.

Expected Browser Render Output

A documentation page showing:

A live interactive card with a clickable blue "Contact" button.
An exact code snippet box below it displaying the source markup <article class="card">...</article> with colorized tags and attributes.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Displaying HTML in HTML</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      line-height: 1.6;
      max-width: 720px;
      margin: 2rem auto;
      padding: 0 1rem;
      background-color: #f8fafc;
      color: #0f172a;
    }

.doc-section {
      background: white;
      border: 1px solid #e2e8f0;
      border-radius: 8px;
      padding: 1.5rem;
      margin-bottom: 2rem;
    }

/* Live Preview Box */
    .preview-box {
      border: 2px dashed #94a3b8;
      border-radius: 6px;
      padding: 1rem;
      margin: 1rem 0;
      background-color: #ffffff;
    }

/* Code Block Display */
    pre {
      background-color: #1e1e2e;
      border-radius: 6px;
      padding: 1.25rem;
      overflow-x: auto;
    }

code {
      font-family: "JetBrains Mono", Consolas, monospace;
      font-size: 0.88rem;
      color: #cdd6f4;
    }

.tag { color: #f38ba8; }
    .attr { color: #f9e2af; }
    .val { color: #a6e3a1; }
  </style>
</head>
<body>
  <h1>Component Tutorial: Semantic Cards</h1>

<div class="doc-section">
    <h2>1. Live Rendered Component</h2>
    <p>Below is how the browser renders the card component:</p>
    
    <div class="preview-box">
      <article class="card">
        <h3>Senior Engineer</h3>
        <p>Specializing in modern web standards and accessibility.</p>
        <button type="button" style="background:#2563eb;color:white;border:none;padding:0.4rem 0.8rem;border-radius:4px;cursor:pointer;">Contact</button>
      </article>
    </div>

<h2>2. Source Code Required to Build It</h2>
    <p>Copy and paste the following HTML snippet into your project:</p>

<pre><code>&lt;<span class="tag">article</span> <span class="attr">class</span>=<span class="val">"card"</span>&gt;
  &lt;<span class="tag">h3</span>&gt;Senior Engineer&lt;/<span class="tag">h3</span>&gt;
  &lt;<span class="tag">p</span>&gt;Specializing in modern web standards and accessibility.&lt;/<span class="tag">p</span>&gt;
  &lt;<span class="tag">button</span> <span class="attr">type</span>=<span class="val">"button"</span>&gt;Contact&lt;/<span class="tag">button</span>&gt;
&lt;/<span class="tag">article</span>&gt;</code></pre>
  </div>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Interactive Code Exporter

Instructions:

Create an HTML documentation widget with a hidden <template id="card-template"> containing an HTML form with a <label>, an <input type="email">, and a <button>Submit</button>.
Provide a <pre><code id="display-area"></code></pre> container.
Write a tiny JavaScript function that reads .innerHTML from the <template> and assigns it to codeElement.textContent (demonstrating how textContent automatically handles all HTML escaping for you).

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Code Exporter</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background-color: #0f172a;
      color: #f8fafc;
      padding: 2rem;
      max-width: 680px;
      margin: 0 auto;
    }

    pre {
      background-color: #1e293b;
      border: 1px solid #334155;
      border-radius: 8px;
      padding: 1.25rem;
      overflow-x: auto;
    }

    code {
      font-family: "Fira Code", Consolas, monospace;
      font-size: 0.9rem;
      line-height: 1.6;
      color: #38bdf8;
      white-space: pre-wrap;
    }

    button.export-btn {
      background-color: #3b82f6;
      color: white;
      border: none;
      padding: 0.6rem 1.2rem;
      font-weight: 600;
      border-radius: 6px;
      cursor: pointer;
    }
  </style>
</head>
<body>
  <h2>Newsletter Component Code</h2>
  <button class="export-btn" onclick="exportCode()">Generate Source Markup</button>

  <!-- Inert Template (Does not render on page) -->
  <template id="newsletter-template">
<form class="newsletter-form" action="/subscribe" method="POST">
  <label for="user-email">Subscribe to our newsletter:</label>
  <input type="email" id="user-email" name="email" placeholder="[email protected]" required>
  <button type="submit">Subscribe</button>
</form></template>

  <h3>Source Code Output:</h3>
  <pre><code id="code-output">Click the button above to load source markup...</code></pre>

  <script>
    function exportCode() {
      const template = document.getElementById("newsletter-template");
      const codeOutput = document.getElementById("code-output");

      // textContent automatically escapes all angle brackets and ampersands
      codeOutput.textContent = template.innerHTML.trim();
    }
  </script>
</body>
</html>

Why this works:

The <template> tag safely holds real HTML markup without rendering it or executing any enclosed logic.
When JavaScript reads template.innerHTML and assigns it to codeOutput.textContent, the browser automatically escapes all < and > characters into safe visual text glyphs without risking Cross-Site Scripting (XSS).

⚠️ Common Pitfalls

Using .innerHTML to Display Code: If you set codeElement.innerHTML = "<div>Hello</div>", the browser will construct a real <div> node instead of displaying the code. Always use codeElement.textContent when injecting raw code strings.
Double-Escaping Ampersands: If you already have < in your text and pass it through an escaping utility twice, it becomes &lt;, rendering as literal text < on the screen.
Using Legacy <xmp> Tags: <xmp> is obsolete in HTML5 and can lead to severe security vulnerabilities and layout breakages across different browsers.

💡 Pro Tips

Automated Build-Time Escaping: When writing technical markdown blogs in Astro, Next.js, or Hugo, the markdown compiler (rehype / remark / markdown-it) automatically escapes code fence blocks (```html) into < and > during static site generation.
Sanitizing User-Submitted Snippets: If building a developer forum or comment system where users submit code snippets, always sanitize and escape using DOMPurify or server-side HTML entity encoders to prevent stored XSS attacks.

📌 Key Takeaways

To display HTML markup as visible text, all < must be escaped as <, > as >, and & as &.
Unescaped HTML tags placed inside <code> or <pre> are parsed by the browser as live DOM nodes.
Legacy elements like <xmp>, <plaintext>, and <listing> are obsolete and should never be used.
The HTML5 <template> element allows storing inactive HTML markup that can be extracted safely via JavaScript.
Setting element.textContent in JavaScript automatically converts raw HTML strings into safely escaped character glyphs.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What character entity must replace the `<` symbol to display `<header>` as raw code in HTML?

Topic: HTML Fundamentals

? Question 2 / 3

Why is the `<xmp>` tag considered obsolete in modern web development?

Topic: HTML Fundamentals

? Question 3 / 3

If you assign a raw HTML string `"<p>Test</p>"` to `element.textContent`, what does the user see on the webpage?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Mandatory Escaping Rules

The Obsolete Historical Traps: <xmp>, <plaintext>, and <listing>

Modern Dynamic HTML Extraction with <template>

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Interactive Code Exporter

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What character entity must replace the < symbol to display <header> as raw code in HTML?

Why is the <xmp> tag considered obsolete in modern web development?

If you assign a raw HTML string "<p>Test</p>" to element.textContent, what does the user see on the webpage?

The Obsolete Historical Traps: `<xmp>`, `<plaintext>`, and `<listing>`

Modern Dynamic HTML Extraction with `<template>`

What character entity must replace the `<` symbol to display `<header>` as raw code in HTML?

Why is the `<xmp>` tag considered obsolete in modern web development?

If you assign a raw HTML string `"<p>Test</p>"` to `element.textContent`, what does the user see on the webpage?