Get started

Installation

Requirements

• Node.js v22 or later
• Eleventy v3 or later

We recommend Node version manager if you are working across projects that use different versions of Node.js.

Create a package.json file if you don’t already have one. You can create a default package.json file by running npm init from the root folder of your project.

Install dependencies

To install, run:

npm install @11ty/eleventy @x-govuk/nhsuk-eleventy-plugin

When the installation finishes, @11ty/eleventy and @x-govuk/nhsuk-eleventy-plugin packages and other dependencies will be in your node_modules folder.

Create a content folder

Next, create a folder to contain all the content for your site, for example docs.

Configure your site

Next, add an eleventy.config.js file to the root folder of your project. You will use this file to configure Eleventy, and set options for the plugin.

Add your chosen folder name to the input key within the eleventy.config.js file:

import { nhsukEleventyPlugin } from '@x-govuk/nhsuk-eleventy-plugin'

export default function(eleventyConfig) {
  // Register the plugin
  eleventyConfig.addPlugin(nhsukEleventyPlugin)

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    dir: {
      // The folder where all your content will live:
      input: 'docs',
    }
  }
};

Generate site pages

To generate a site, type the following command:

npx eleventy --serve

Once Eleventy has generated all the files, the terminal will show a preview URL which you can enter into your browser’s address bar:

[11ty] Copied 14 files / Wrote 0 files in 1.11 seconds (v2.0.0)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

Whenever you add a new page, or edit an existing one, the browser will automatically refresh with any of your changes applied.

By default, generated pages will get saved to a /_sites folder. You can change the same of this folder by adding a new folder name to dir.output in eleventy.config.js.

Create your first page

You’re now ready to start adding pages to your site.

Pages have 2 parts: a front matter and its contents.

A front matter starts and ends with --- and uses a key/value data format called YAML. In most cases, you will need 2 bits of information: layout and title. For example:

---
homepage: true
layout: page
title: My first page
---
This is my first page, built using Eleventy and `@x-govuk/nhsuk-eleventy-plugin`.

Create a file named index.md file within the folder you created, and add the above content.

The first page in your site should also have a homepage value set to true¹. Eleventy uses this to work out the structure of your site if it has nested pages.

Open the preview URL in your browser to see this new page appear using NHS.UK styles.

Choose a layout

This plugin provides 6 different layouts for presenting content, each with different options you can provide in the front matter:

• Collection – Layout for a paginated list of pages or posts.

• Hub – Layout for a curated list of pages or posts, optionally grouped by section.

• Page – Simple layout designed for maximum flexibility of content.

• Page with sub navigation – Layout with sub navigation.

• Post – Layout for date-based content, such as blog posts or news items.

• Product page – Layout for product and marketing pages.