Theory: Tags and content

The first thing you should learn when learning Pug is HTML syntax. It is not very complicated but has several key points affecting the markup compilation.

Pug has no concept of opening and closing tags. We can type in all tags. There is no need to close them. For example:

p
div
span
form

displays

<p></p>
<div></div><span></span>
<form></form>

It is one of the reasons why developers love HTML preprocessors. How many times have you made the mistake of not closing a tag? That will not happen here.

Pug places block elements on new lines and line elements on the same line when it compiles to HTML. It can be confusing, but you rarely need to work with that.

There are three styles of embedded content inside tags:

1. Inline: we place all content immediately after the tag is designated
2. Pipe: we arrange all content on several lines where each line beginning with |
3. Block: we arrange all content in several lines with a period straight after the tag

p This is inline. Inside the tag will be all the content you put in the line.

p
  | Pipe style content
  | Each line begins with a vertical line

p.
  Block: We can set here any number of lines.
  And we do it without any special characters.

<p>This is inline. Inside the tag will be all the content you specify in the line.</p>

<p>
  Pipe
  Each line begins with a vertical line
</p>

<p>
  Block: We can set here any number of lines.
  And we do it without any special characters.
</p>

Whitespace characters are the trickiest part of working with Pug text. Try different versions of the texts and tags in it. At the end of this lesson, we will discuss this issue in more detail.

Tag nesting

Pug uses indentation to create nesting. There can be any number of them. It is often guided based on the standard indentation in HTML — two spaces. For example:

section
  p I am a nested paragraph in the
section
  h2 The best products in our store
  div
    h3 Product 1
    p Price: 55 rubles

<section>
  <p>I am a nested paragraph in a section</p>
</section>

<section>
  <h2>Best products in our store</h2>
  <div>
    <h3>Item 1</h3>
    <p>Price: 55 rubles</p>
  </div>
</section>

It is important to keep the same amount of indentation in all nested elements. In most cases, Pug will understand the markup correctly with varying amounts of indentation, but they could lead to errors.

Attributes

Pug provides several options for adding attributes:

1. Using parentheses. With this option, we can add all arguments, including custom ones
2. Special syntax for classes and identifiers. Designated inside the markup, they are similar to CSS selectors

section(id='news-container' class='container')
section#news-container.container

<section class="container" id="news-container"></section>
<section class="container" id="news-container"></section>

In development, we use the second syntax for classes and all other attributes written in parentheses. There are no established standards here, but using it like this allows you to shorten your code in the following way.

If you do not specify a tag but write a class right away, Pug will automatically create a <div> with the correct class:

.container(data-container='news')
  .row
    .col
      p Here's some text

<div class="container" data-container="news">
  <div class="row">
    <div class="col">
      <p>Here is some text</p>
    </div>
  </div>
</div>

In real-life tasks, you should not mix and match approaches. If the project does not specify a div with a class, it is worth following this approach. Always keep the overall style. If others working on the project used div, then you should too.

Tag interpolation

This tagging technique is rare, but you should always consider it. Pug allows you to use a specific construct to add a tag within the text. It helps prevent the text from being split into several different parts.

For example, how do you insert a tag inside such a paragraph? Here is the way:

p.
  Hexlet is a hands-on programming course platform.
  We help beginners become professionals and assist experienced developers to gain new knowledge and grow professionally.

Pug allows you to wrap the part you want in a tag, but then you lose the semantics of using the preprocessor. In the end, we mix regular HTML with Pug syntax:

p.
  Hexlet is a platform with <strong>practical</strong> programming courses.
  We help beginners become professionals and assist experienced developers to gain new knowledge and grow professionally.

The #[content tag] construct helps you avoid this:

p.
  Hexlet is a platform with #[strong practical] programming courses.
  We help beginners become professionals and assist experienced developers to gain new knowledge and grow professionally.

<p>Hexlet is a platform with <strong>practical</strong> programming courses.
  We help beginners become professionals and assist experienced developers to gain new knowledge and grow professionally.
</p>

Whitespace symbols

The most common problem in learning Pug is understanding indentation. At first glance, it may seem that this is not a problem — add some indents and see them in the HTML.

In most cases, Pug will render all the whitespace as you set it, but there are some quirks. Let us look at an example of some pipe-style text content.

Pipe style comes in handy when you use tags within the text. For example:

div
  | Want to get an item?
  | Use the
  button Order button
  | button and leave your contact details

You most likely expect the following result when translating to HTML:

<div>Want to get an item? Use the <button>Order</button> button and leave your contacts details</div>

You end out with this markup:

<div>Want to get an item? Use the<button>Order</button>button and leave your contact details</div>

Note the whitespace around the <button> tag, or lack thereof. Pug removes all whitespace between elements. This example has text and a button. Since these are two elements, the interpreter removes the whitespace between them because it has no real meaning. It helps to remove extra characters between tags but causes problems when you add an element inside the text.

There are several options for solving this problem:

1. Add an empty pipe string that converts to a whitespace character
2. Use an HTML mnemonic
3. Add extra spaces. You can do this, but you should not. We will discuss the reasons later

An empty pipe string is something of an official hack. Every pipe string should return some symbol, which has an unexpected benefit for developers.

If the string is empty, the interpreter will insert a space. The final code will look a little messy, but it is decent enough to use this method. All you have to do is add a blank line before and after the element:

div
  | Want to get an item?
  | Use the
  |
  button Order button
  |
  | button and leave your contact details

<div>Want to get an item? Use the <button>Order</button> button and leave your contacts details</div>

The second way to solve the problem is to use an HTML mnemonic, a specific construct that the browser translates into the desired characters. For non-breaking spaces, we have the   symbol.

By adding it before and after the button, you can prevent characters from disappearing:

div
  | Want to get an item?
  | Use the  
  button Order
  |  button and leave your contact details

<div>Want to get an item? Use the&nbsp;<button>Order</button>&nbsp;and leave your contact details</div>

Try adding this HTML code to your file and see how the browser converts the mnemonics to the correct characters.

The final method that might help in the example above is to add separate spaces to the pug markup. This method is similar to mnemonics, but you add a character instead of using them.

Pug does not remove whitespace within an element. If you add a thousand whitespace characters between two words, the interpreter will carefully include them in the markup. So all you have to do is add a space afteruse the and before button and leave your contact details.

While this method works, there are a few problems with it:

1. This type of markup is hard to read. It is not always possible to immediately understand how many spaces there are before the line, and the number of spaces after the line is not visible at all
2. Most code editors automatically remove characters at the end of a line because they are usually unnecessary. In this case, there is no way to add a space after the phrase use the

Additional assignment

Using Pug syntax, reproduce the following markup:

<section class="container">
  <div class="col-2">
    <div class="content">
      <h1>About Hexlet</h1>
      <p>Hexlet is a platform for hands-on programming courses. We help beginners become professionals and assist experienced developers in gaining new knowledge and growing professionally.</p>
    </div>
    <div class="side">
      <ul>
        <li><strong>Theory.</strong>It is a short lecture in text or video form. It is task-based, so unlike traditional academic theory, we focus on a problem already solved by bright engineers and programmers and then follow their steps to understand the solution.</li>
        <li><strong>Test.</strong>It is a way to test your understanding of the material. We do not care about memorizing facts, so we ask questions that challenge your understanding of the concept, not your memory.</li>
        <li><strong>Practice.</strong>There are programming exercises in a real development environment, accessible through the browser. Not a simulation or a toy, but on a real machine with databases, frameworks, servers, and other tools.</li>
      </ul>
    </div>
  </div>
</section>