Comments

A comment is a note in the code that the browser does not display. Pug has two kinds: a plain // ends up in the finished HTML as , while a //- comment stays in the template only and never reaches the result.

A comment in the HTML

A line starting with // becomes an HTML comment. Add to src/index.pug:

// Site header
header
  h1 Morning Café

In the result the comment sits before header:

<!-- Site header-->
<header>
  <h1>Morning Café</h1>
</header>

Visitors do not see it on the page, but they can read it by opening the page source in the browser.

A template-only comment

Add a hyphen — //- — and the comment stays in the .pug file:

header
  //- Add the logo when the designer sends the file
  h1 Morning Café

Nothing of the note is left in the HTML:

<header>
  <h1>Morning Café</h1>
</header>

These comments suit notes for developers: they do not make the page bigger and visitors cannot see them.

A multi-line comment

If nothing follows // or //-, all the lines indented below become the comment:

//
  The menu is updated
  every Monday
p There are five drinks on the menu today.

The indented lines became one HTML comment:

<!--
The menu is updated
every Monday
-->
<p>There are five drinks on the menu today.</p>

This is also a handy way to switch off a piece of markup for a while: put //- above it and indent it one level.

Which one to use

Syntax	Ends up in the HTML	Used for
`//`	Yes	Section labels in the finished page code
`//-`	No	Notes for yourself and the team, disabled code

Common mistake

Writing with a plain // things visitors should not see: internal plans, names of service files or the address of a test server. Such a comment ends up in the page code, and any visitor can read it with "View source". For every note not meant for the HTML, use //-.

Thanks for reading!