Skip to main content
  1. X-GOVUK projects
  2. GOV.UK Eleventy Plugin

Layouts

The plugin offers a number of layouts to match the type of content you want write.

  • 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.

  • Collection – Layout for a paginated list of pages.

  • Product page – Layout for product and marketing pages.

Common front matter options

Layouts can accept the following front matter data to customise the appearance, content and behaviour of a layout.

Name Type Description
layout string Page layout.
includeInBreadcrumbs boolean

Include page as the last item in any breadcrumbs (default is false).

order integer Ranking of page in navigation. Lower numbers appear before pages with a higher number.
title string Page title.
description string Page description.
opengraphImage object Open Graph image that appears on social media networks.
opengraphImage.src string

Path to Open Graph image. Can be a relative or absolute URL. This value overrides opengraphImageUrl in plugin options.

opengraphImage.alt string Alternative text for Open Graph image.
aside object Small portion of content that is indirectly related to the main content.
aside.title string Title for aside.
aside.content string Content for aside. Accepts Markdown.
related object

Related links section. See section.

related.sections Array

Multiple related links sections. See section.

Options for section
Name Type Description
title string Title for group of related links (default is ‘Related content’).
items Array

See items.

subsections Array Subsections containing related links.
subsections[].title string Title for a subsection of related links.
subsections[].items Array

Related items in a subsection. See items.

Options for items
Name Type Description
text string Title of related content.
href string Link for the related content.

Overriding layouts

Layouts are registered with Eleventy by setting the dir.layouts key to point to the layout files installed in the package directory:

const govukEleventyPlugin = require('@x-govuk/govuk-eleventy-plugin')

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin)

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    dir: {
      layouts: 'node_modules/@x-govuk/govuk-eleventy-plugin/layouts'
    }
  }
};

If you want to use your own layouts, remove this value and set a value for dir.includes (and optionally dir.layouts).

You can use layouts provided by this plugin as a basis for your own. For example, to show a notification banner at the top of a page, extend the page layout:

{# Plugin layouts can be loaded from "layouts" #}
{% extends "layouts/page.njk" %}

{# Load any GOV.UK Frontend components #}
{% from "govuk/components/notification-banner/macro.njk" import govukNotificationBanner %}

{% block content %}
  {# Templates can include front matter data #}
  {{ govukNotificationBanner({
    text: "This page was last reviewed on " + (reviewed | date("d LLLL y")) + ".
    It needs to be reviewed again on " + (reviewAgain | date("d LLLL y")) + "."
  }) if reviewed and reviewAgain }}

  {{ appDocumentHeader({
    title: title,
    description: description
  }) }}

  {{ appProseScope(content) if content }}
{% endblock %}