HTML: Preprocessor Pug
2026-02-21 23:42 Diff
https://hexlet.io/courses/html-pug/lessons/include/theory_unit

The advantage of Pug over plain HTML is that it allows you to include files. Imagine a project with five static pages. Some sites of this size do not use CMS or other server solutions to manage the site template. Firstly, it is faster because there is no additional processing, and secondly, it lowers the entry threshold for the project.

However, a static solution has a global problem — too many repeated blocks of HTML. These are usually footers, headers, menus, banners, and more. Copying HTML is not the best solution because you end up with different blocks at some point.

It is where Pug comes in. It allows you to create separate files for repeating elements and include them in any file. As we will see in this lesson, it can contain markup and any data, including Markdown and other interpretations of files.

For example, let us create some Pug files with header and footer markup:

We can include these files within any other Pug files by using the include construct and giving the path to the file to be included:

When the interpreter processes index.pug file, it puts all the files in their proper places. In this case, you can compile only the most essential files instead of all. We have already seen a similar structure for linking files in the course on the SASS preprocessor:

Pug allows you to connect any file type. The logic is simple enough — we insert the data of any attached file as it is. In this way, you can link not only templates with Pug syntax but also scripts, CSS code, and text data:

Additional modules

When working with Pug, you can use the built-in functions extending them with other handlers. You can do this by interacting with jstransformer.

We'll use the addition of markdown files to the markup as an example. Markdown is a text markup language that we can convert to HTML. When we use this type of writing, we make it easier to read. This way, people unfamiliar with layout design can mark up text correctly.

For example, let us convert the following text:

By the way, Hexlet authors write their text courses in Markdown format, which is automatically converted to HTML markup when uploaded to the server.

The Pug preprocessor uses the package jstransformer-markdown-it to convert Markdown to HTML. We can set it using the command:

To connect a module, we use the syntax :name-module. The script will process everything inside the module:

We intentionally format the final HTML code so you can easily read it during the lesson. If you repeat the steps in the tutorial, Pug may give you a slightly different formatting. It isn't a problem or a mistake.

Inside the modules, you can also pass a file to connect. It is a priority option because it is better not to have the text inside the Pug files and store them separately instead. It is a big topic devoted to application architecture, but you should keep the text and the output separate. The less text Pug contains, the easier it is to work with.

To connect a file to a module, we use include again, followed by the module name and the file to be connected:

Additional assignment

Create a basic HTML page markup using Pug and add the following markdown text: