Comments and code formatting

As a document grows, make its source easy to understand. An HTML comment leaves a note in the source:

<!-- Club introduction -->
<p>New members are welcome.</p>

Comments start with <!-- and end with -->. They do not appear as page content, but visitors can still read them in the source. Never put secrets or private information in comments. You can temporarily comment out markup; do not nest comments inside other comments.

Indentation is for the reader

We usually indent nested elements by two spaces. A p inside body is indented one level further than body. This makes relationships visible but does not replace correct closing tags.

In normal HTML text, consecutive whitespace characters and source line breaks usually collapse into one space. Two source lines do not necessarily become two visible lines. Use separate p elements for separate paragraphs, or br for a meaningful line break within one paragraph. CSS will later control layout and spacing.

Display the characters of a tag

Writing <p> directly creates markup. To display its brackets, use character references: < for less-than, > for greater-than and & for an ampersand. Each starts with & and ends with a semicolon.

<p>A paragraph starts with &lt;p&gt;.</p>
<p>Tea &amp; books</p>

The browser displays the tag characters as text; it does not parse those displayed characters again as a new element.

Compare indented and compact code in the Lab. Their page structure is the same. Add a comment, check that it is absent from the page, then use character references to show literal tag characters. You now have the syntax foundation needed for the following HTML chapters.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Leaflet Club</title>
</head>
<body>
  <!-- A note for the author -->
  <h1>Tea &amp; books</h1>
  <p>A paragraph starts with &lt;p&gt;.</p>
</body>
</html>