Make Multipage HTML Development Suck Less with Pug

If you‘ve ever developed a website with multiple HTML pages, you know how tedious and error-prone it can be. You end up with a lot of duplicated code for common elements like the , header, and footer. Making a small change requires editing every single page. It‘s a hassle to keep everything consistent and in sync.

But there‘s a better way! By using a templating language like Pug, formerly known as Jade, you can greatly simplify the process of building multipage HTML sites. Pug makes it easy to reuse code, reduce duplication, and keep your project more organized and maintainable.

What is Pug?

Pug is an HTML templating language that compiles to HTML. It uses indentation rather than closing tags to define the structure of the document. This results in very concise and readable code. For example, here‘s a simple Pug template:

doctype html
html
head
title My Page
body
h1 Welcome
p Hello world!

Pug has a lot of powerful features like variables, includes, mixins, conditionals, and loops that make it really flexible. But perhaps the biggest benefit of Pug for multipage sites is the ability to extend a base layout template. This allows you to define the common structure and elements once, then override only the parts that change on each page.

Why Use Pug for HTML Development?

Here are some of the key benefits of using Pug to build HTML pages, especially multipage websites:

• Code reuse – Define common code in a layout that each page extends
• Less repetition – No more copying and pasting the same and tags everywhere
• Easier maintenance – Make a change in one place instead of on every page
• Cleaner, more readable code – Indentation-based structure is easier on the eyes
• HTML preprocessing – Use variables, conditionals, iteration in your HTML
• Partials and includes – Break up HTML into smaller, more modular and reusable chunks
• Mixins for UI components – Create custom tags for reusable UI elements

Setting Up a Pug Project

To use Pug, you‘ll need to set up a Node.js project and install a few dependencies. First, create a new directory for your project and run npm init inside it to generate a package.json file. Then install these dependencies:

npm install --save-dev pug pug-loader webpack webpack-cli html-webpack-plugin

This will install Pug itself, the Pug loader for Webpack, Webpack to compile the Pug templates, and the HTML Webpack plugin to generate HTML files from the compiled templates.

Next, set up a src directory for your Pug templates and a webpack.config.js file to configure Webpack. Here‘s an example folder structure:

src/
  includes/
    head.pug
    header.pug
    footer.pug
  pages/
    index.pug
    about.pug
    contact.pug
  layout.pug
webpack.config.js
package.json

Creating a Layout Template

The key to code reuse in multipage Pug sites is the layout template. This defines the common structure and elements that will be shared by all pages. Here‘s an example layout.pug file:

doctype html
html
  head
    include includes/head.pug
  body
    include includes/header.pug

    block content

    include includes/footer.pug

This layout does a few important things:

It defines the overall document structure with the doctype, html, head, and body tags.
It includes a head.pug partial file to contain the contents of the <head> tag, which will be shared by all pages.
It includes a header.pug partial for the <header> that appears at the top of every page.
It defines a block called "content" where page-specific content will be inserted.
It includes a footer.pug partial for the common <footer>.

The block is the most important part. This serves as a placeholder that can be overridden by each individual page template.

Creating Page Templates

With the layout.pug in place, you can now create a separate .pug file for each page on your site. Here‘s an example index.pug page template:

extends layout.pug

block content
  h1 Welcome to my site
  p This is some page-specific content
  ul
    li Item A
    li Item B

The key things here are:

The extends declaration tells Pug that this template should inherit from layout.pug.
The block content fills in the content block defined in the layout with the page-specific HTML.

This approach makes the page template extremely minimal and readable, containing only the unique content for that page. The common code is all contained in the layout.pug and various partials.

To create additional pages, just add a new .pug file for each one, extending layout.pug and defining its unique content. For example, about.pug might contain:

extends layout.pug

block content
  h1 About Us
  p We are a small but mighty team of developers...

Using Includes for Partials

In addition to the layout, you can use Pug‘s include feature to break up your code into smaller, more modular chunks known as partials. A common example is a navigation menu. Rather than copying and pasting the

into every page, you can define it once in a nav.pug partial:

//- nav.pug
nav
  ul
    li: a(href="/") Home
    li: a(href="/about") About
    li: a(href="/contact") Contact

Then in layout.pug, you can include it before the content block:

include includes/header.pug
include includes/nav.pug

block content

Now every page will automatically include the navigation without duplicating code. You can use includes to modularize any chunk of HTML you find yourself repeating, such as tags, includes, sidebar content, and so on.

Converting Existing HTML to Pug

If you have an existing site built with plain HTML, you can convert it to Pug gradually. Start by creating layout.pug with the common elements, then create a .pug file for each page, copy in the unique HTML, and replace it with Pug syntax.

Here are some tips for converting HTML to Pug:

• Indentation matters! Pug uses indentation rather than closing tags to define nesting.
• Use : after a tag to define its content on the same line – h1: Welcome
• Attributes go in parentheses after the tag name – a(href="http://example.com")
• Omit div tags – Pug assumes a div if you don‘t specify the tag name
• Use = or – to insert dynamic content and logic

For example, an HTML navigation like:

<nav>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

Would be written in Pug like:

nav
  ul
    li: a(href="/") Home 
    li: a(href="/about") About
    li: a(href="/contact") Contact

Taking it piece by piece and using lots of includes makes converting a large site manageable.

Using Mixins for UI Components

Mixins are one of the most powerful features of Pug. They let you define reusable chunks of code almost like HTML components. For example, let‘s say your site has a number of product cards, which are

s with an image, a title, and a price. Instead of writing the full HTML for each one, you can define a productCard mixin:

mixin productCard(product)
  .product-card
    img.product-card__image(src=product.image)
    h3.product-card__title= product.title
    span.product-card_price $#{product.price}

Then you can render a product card like this:

+productCard({ 
  image: ‘/images/foo.jpg‘,
  title: ‘Product Name‘, 
  price: ‘99.99‘
})

This can drastically simplify your page templates and make your UI more consistent. Any time you find yourself repeating a piece of your UI, consider extracting it to a mixin.

Putting It All Together with Webpack

Once you‘ve broken up your HTML into a layout, pages, and includes, you need a way to compile it all into the final HTML output. This is where Webpack comes in. With the pug-loader and html-webpack-plugin, it can compile .pug files into HTML. Here‘s a basic webpack.config.js:

const path = require(‘path‘);
const HtmlWebpackPlugin = require(‘html-webpack-plugin‘);

module.exports = {
  entry: ‘./src/app.js‘,
  output: {
    path: path.resolve(__dirname, ‘dist‘),
    filename: ‘[name].bundle.js‘
  },
  module: {
    rules: [
      {
        test: /\.pug$/,
        loader: ‘pug-loader‘
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: ‘./src/pages/index.pug‘,
      filename: ‘index.html‘
    }),
    new HtmlWebpackPlugin({
      template: ‘./src/pages/about.pug‘,
      filename: ‘about.html‘
    })
  ]
};

This tells Webpack to:

Load .pug files with the pug-loader
Compile src/pages/index.pug into dist/index.html
Compile src/pages/about.pug into dist/about.html

You‘ll need an HtmlWebpackPlugin entry for each page template you want to compile.

Best Practices

Here are a few tips I‘ve learned from experience with large Pug projects:

• Use consistent naming conventions for layouts, pages, includes, and mixins
• Keep mixins small and focused – if they get too big, consider breaking them up
• Don‘t overuse Pug‘s extended features like conditionals and iteration – a little goes a long way and overuse can make templates hard to read
• Use block append / prepend sparingly – they make the layout harder to reason about
• If something is hard to express in Pug, it‘s okay to just use plain HTML

When Not to Use Pug

Pug is great for many use cases, but there are some scenarios where it may not be the best fit:

• Sites with a lot of user-editable content – non-technical users may find Pug syntax confusing
• Projects where the HTML will be edited by many people, some of whom may not know Pug
• When full control over the HTML output is required, such as content that will be ingested by another system that expects specific markup

In these cases, you may want to consider a different templating language like Handlebars or EJS, or a content management system with a WYSIWYG editor.

Conclusion

I hope this deep dive into using Pug for multipage websites has given you a sense of how it can greatly simplify HTML development. By reducing code duplication, increasing modularity, and eliminating a lot of the tedious grunt work of writing HTML, Pug can make you a happier and more productive developer.

It takes some time to get used to Pug‘s unique syntax, but once it clicks, you‘ll find it very intuitive and much easier to read and maintain than raw HTML. So give it a try on your next project! And if you want to learn more, check out the official Pug documentation and join the Pug community.

Make Multipage HTML Development Suck Less with Pug

What is Pug?

Why Use Pug for HTML Development?

Setting Up a Pug Project

Creating a Layout Template

Creating Page Templates

Using Includes for Partials

How to Create a Production-Ready Webpack 4 Config From Scratch

Learn Webpack to Simplify and Speed Up Your Website

How to Share Variables Across HTML, CSS, and JavaScript Using Webpack

How to Use Webpack with React: An In-Depth Tutorial

What is Pug?

Why Use Pug for HTML Development?

Setting Up a Pug Project

Creating a Layout Template

Creating Page Templates

Using Includes for Partials

Similar Posts