GOV.UK Eleventy Plugin

https://github.com/x-govuk/govuk-eleventy-plugin
Admin
A plugin for building documentation websites using Markdown and GOV.UK styles with Eleventy static...
Tokens:23,898
Snippets:251
Trust Score:9.1
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Create First Page with YAML Front Matter

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/install.md

This example demonstrates the structure of an Eleventy page using Markdown. It includes YAML front matter for metadata like `homepage`, `layout`, and `title`, followed by the page content.

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

--------------------------------

### Generate Site Pages with Eleventy

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/install.md

This command starts the Eleventy development server, which builds your site and serves it locally. It also watches for file changes and automatically rebuilds the site and refreshes the browser.

```shell
npx eleventy --serve
```

--------------------------------

### Eleventy Navigation Key Example

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/install.md

This YAML snippet shows an alternative way to set the `homepage` property using `eleventyComputed` and `eleventyNavigation`. This is useful for defining the key for the home navigation item.

```yaml
eleventyComputed:
  eleventyNavigation:
    key: "{% raw %}{{ config.homeKey }}{% endraw %}"
```

--------------------------------

### Install GOV.UK Eleventy Plugin and Dependencies

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/install.md

This command installs the necessary packages for the GOV.UK Eleventy Plugin and Eleventy itself. It adds these packages to your project's `node_modules` folder, making them available for use.

```shell
npm install @11ty/eleventy @x-govuk/govuk-eleventy-plugin
```

--------------------------------

### Install GOV.UK Eleventy Plugin via npm

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/README.md

This command installs the GOV.UK Eleventy Plugin using npm. Ensure you have Node.js and npm installed on your system.

```bash
npm install @x-govuk/govuk-eleventy-plugin
```

--------------------------------

### Govspeak Example Callout Formatting

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Creates an example callout block using the $E delimiter in Govspeak markdown. This is used to highlight example content, which can span multiple lines and paragraphs, and may include links.

```markdown
$E
**Example** This is an indented example block.
It may span multiple lines and [contain links](#).

It may even span multiple paragraphs.
$E
```

--------------------------------

### GET /applications

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/collection.md

Retrieves a list of all applications.

```APIDOC
## GET /applications

### Description
Get many applications.

### Method
GET

### Endpoint
/applications

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **applications** (array) - A list of application objects.

#### Response Example
```json
{
  "applications": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Example App",
      "status": "pending"
    }
  ]
}
```
```

--------------------------------

### Product Layout Configuration in YAML

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Sets up a marketing-style landing page using the 'product' layout. Includes options for a masthead, start button, featured image, and related content sections.

```yaml
---
homepage: true
layout: product
title: Build Documentation Sites Fast
description: Create professional documentation using Markdown and GOV.UK styles.
inverseMasthead: true
startButton:
  text: Get Started
  href: /get-started/install
image:
  src: /assets/hero-image.svg
  alt: Documentation website illustration
  hideOnMobile: true
related:
  sections:
    - title: Popular pages
      items:
        - text: Installation Guide
          href: /get-started/install
        - text: Configuration Options
          href: /get-started/options
---

<div class="govuk-grid-row">
  <section class="govuk-grid-column-one-third-from-desktop">
    <h2 class="govuk-heading-m">Easy Setup</h2>
    <p class="govuk-body">Get started in minutes with npm install.</p>
  </section>
  <section class="govuk-grid-column-one-third-from-desktop">
    <h2 class="govuk-heading-m">GOV.UK Styles</h2>
    <p class="govuk-body">Professional government design out of the box.</p>
  </section>
  <section class="govuk-grid-column-one-third-from-desktop">
    <h2 class="govuk-heading-m">Markdown First</h2>
    <p class="govuk-body">Write content in Markdown, we handle the rest.</p>
  </section>
</div>

```

--------------------------------

### Configure Eleventy with GOV.UK Plugin

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/install.md

This JavaScript configuration file sets up Eleventy and registers the GOV.UK Eleventy Plugin. It specifies the input directory for content and sets the template engines to Nunjucks (njk).

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

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

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

--------------------------------

### Run Development Server with Eleventy

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Build and serve your documentation site locally with live reload using the Eleventy CLI. This command generates the site files and starts a development server, typically accessible at http://localhost:8080/. It also shows how to build for production or use a custom configuration file.

```bash
npx eleventy --serve

# Output:
# [11ty] Wrote 25 files in 1.54 seconds
# [11ty] Watching...
# [11ty] Server at http://localhost:8080/

# Build for production
npx eleventy

# Build with custom config file
npx eleventy --config=docs.config.js
```

--------------------------------

### Add GOV.UK Eleventy Plugin to Eleventy Configuration

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/README.md

This JavaScript code snippet demonstrates how to import and add the govukEleventyPlugin to an Eleventy configuration file. It requires the '@x-govuk/govuk-eleventy-plugin' package to be installed.

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    // Options
  })
}
```

--------------------------------

### Deploy Eleventy Site with GitHub Actions

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/hosting.md

This YAML configuration automates the building and deployment of an Eleventy site to GitHub Pages. It checks out the code, sets up the environment, installs dependencies, builds the Eleventy site, and uploads the artifacts for deployment. It requires permissions for contents, pages, and id-token.

```yaml
name: deploy

on:
  push:
    branches:
      - main

# Set permissions of GITHUB_TOKEN
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v5
    - name: Setup Pages
      uses: actions/configure-pages@v5
    - name: Install dependencies
      run: npm ci
    - name: Build with Eleventy
      run: npm run-script build
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v4

  deploy:
    environment:
      name: github-pages
      url: ${% raw %}{{ steps.deployment.outputs.page_url }}{% endraw %}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### GET /applications/:id

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/collection.md

Retrieves a single application by its ID.

```APIDOC
## GET /applications/:id

### Description
Get a single application.

### Method
GET

### Endpoint
/applications/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the application.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the application.
- **name** (string) - The name of the application.
- **status** (string) - The current status of the application.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Example App",
  "status": "pending"
}
```
```

--------------------------------

### Update Service Navigation Options in Eleventy Plugin

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/upgrading/6-to-7.md

This example illustrates the renaming of configuration options for service navigation in the GOV.UK Eleventy Plugin. It shows the transition from `navigation` and `navigation.items` to `serviceNavigation` and `serviceNavigation.navigation`.

```javascript
eleventyConfig.addPlugin(govukEleventyPlugin, {
      navigation: {
        items: [{
          text: 'API reference',
          href: '/api'
        }, {
          text: 'Glossary',
          href: '/glossary'
        }]
      }
    })
```

```javascript
eleventyConfig.addPlugin(govukEleventyPlugin, {
      serviceNavigation: {
        navigation: {
          text: 'API reference',
          href: '/api'
        }, {
          text: 'Glossary',
          href: '/glossary'
        }
      }
    })
```

--------------------------------

### Markdown Paragraphs and Line Breaks

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Demonstrates how to create paragraphs by separating text with blank lines and how to insert line breaks using two or more spaces at the end of a line.

```markdown
This is the first paragraph.

And this is the second one.
```

```markdown
This is the first line.  
And this is the second one.
```

--------------------------------

### Create Basic Tables in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Shows the fundamental Markdown syntax for creating tables using hyphens for headers and pipes to separate columns. Cell widths can vary.

```markdown
| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |
```

```markdown
| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |
```

--------------------------------

### Generate HTML-Base URL for RSS Feed Example (Nunjucks)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/feed.md

This Nunjucks code snippet generates an HTML-safe URL for an example RSS feed. It uses the `htmlBaseUrl` filter to ensure the URL is correctly encoded and safe for embedding in HTML, combining a base path with a potentially modified URL.

```njk
{{ "/example/feed.xml" | htmlBaseUrl(url) }}
```

--------------------------------

### Create Basic Links in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Demonstrates how to create a basic hyperlink by enclosing the link text in square brackets and the URL in parentheses. This is a standard Markdown feature.

```markdown
Visit [GOV.UK](https://www.gov.uk).
```

--------------------------------

### Create Linked Images in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Demonstrates how to make an image clickable by wrapping the image Markdown syntax within link syntax (brackets for the image, parentheses for the URL).

```markdown
[![A stylised crown icon.](/assets/rebrand/images/govuk-icon-180.png)](https://www.gov.uk)
```

--------------------------------

### Utilize Markdown Features and Govspeak with GOV.UK Eleventy Plugin

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Extends standard Markdown with GOV.UK-specific features like alerts, callouts, and Govspeak syntax. This includes support for GitHub-style alerts, blockquotes with attribution, various callout types (information, warning, example), address blocks, tables of contents, and advanced typography.

```yaml
---
layout: page
title: Writing Content
---
```

```markdown
## Alerts (GitHub-style)

> [!NOTE]
> Important information users should know.

> [!WARNING]
> Urgent information requiring immediate attention.

> [!TIP]
> Helpful suggestions for users.

## Blockquotes with Attribution

> Many forms of Government have been tried in this world of sin and woe.
> No one pretends that democracy is perfect or all-wise.
>
> -- Winston Churchill, 1947

## Govspeak Callouts

^This is an information callout for general notices.^

%This is a warning callout for important alerts.%

$E
**Example** This is an example callout block.
It can span multiple paragraphs.
$E

## Govspeak Address

$A
HM Revenue and Customs
Bradford
BD98 1YY
$A

## Table of Contents

[[toc]]

## Advanced Typography

- Fractions: 1/2, 1/4, 3/4
- Dashes: -- (en dash), --- (em dash)
- Quotes: "smart quotes" and 'apostrophes'
- Subscript: H~2~O
- Superscript: E=mc^2^
- Highlighted: ==important text==
- Deleted: ~~removed text~~
- Inserted: ++added text++

## Description Lists

Term One
: Definition for the first term.

Term Two
: First definition for term two.
: Second definition for term two.
```

--------------------------------

### Enable Pagination in Sub Navigation Layout (YAML)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/sub-navigation.md

This example shows how to enable previous and next page links at the bottom of a page using the 'showPagination' option within the 'sub-navigation' layout's front matter. It also demonstrates how to set a custom order for pages using the 'order' front matter option, which is useful for controlling the sequence of linked pages.

```yaml
---
layout: sub-navigation
title: Second page title
order: 2
---

This is the second page
```

--------------------------------

### Add GitHub-Style Alerts to Markdown (Diff)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/upgrading/7-to-8.md

This snippet demonstrates the addition of GitHub-style Markdown alerts for emphasizing critical information. The example shows how to replace previous blockquote syntax used for inset text with a '[!NOTE]' alert, improving the clarity and semantic meaning of informational content.

```diff
+ > [!NOTE]
  > No one pretends that democracy is perfect or all-wise.

```

--------------------------------

### Create Description Lists in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Learn how to create description lists in Markdown by typing the term on the first line, followed by a colon and the description on the next line. Multiple descriptions can be added for a single term.

```markdown
First Term
: This is the description of the first term.

Second Term
: This is one description of the second term.
: This is another description of the second term.
```

--------------------------------

### Create Links from URLs and Email Addresses in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Shows how to automatically convert URLs and email addresses into clickable links by enclosing them in angle brackets. This is useful for direct web or email references.

```markdown
<https://www.gov.uk>
<mailbox@example.org>
```

--------------------------------

### Format Links with Emphasis and Code in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Illustrates how to apply emphasis (bold) to link text using asterisks and how to format link text as code using backticks. This enhances link readability and context.

```markdown
Visit the **[Markdown Guide](https://www.markdownguide.org)**.
See the section on [`code`](#code).
```

--------------------------------

### Create Footnotes in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Explains the Markdown syntax for creating footnotes, using `[^identifier]` for references and `[^identifier]: Footnote text` for the content. Footnotes can be placed anywhere except within specific block elements.

```markdown
Here’s a simple footnote,[^1] and here’s a longer one.[^longer]

[^1]: This is the first footnote.

[^longer]: Here’s the second, which has 2 paragraphs.

    Indent any following paragraphs to include them in the footnote.
```

--------------------------------

### Markdown Alerts

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Explains how to use markdown syntax to create different types of alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION). Alerts are based on blockquote syntax and can be used to emphasize critical information. They render as inset text, with specific types having colored borders and backgrounds.

```markdown
> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```

--------------------------------

### Markdown Unordered Lists

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Illustrates how to create unordered lists using markdown. List items can be prefixed with dashes (-), asterisks (*), or plus signs (+). Indentation is used for creating nested lists. Different list types can also be nested within each other.

```markdown
- First item
- Second item
  - Indented item
  - Indented item
- Third item
```

--------------------------------

### Markdown Unordered List Items Starting with Numbers

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Explains how to start an unordered list item with a number followed by a period in markdown. This is achieved by escaping the period with a backslash (`\`). This prevents the markdown parser from interpreting the item as the start of an ordered list.

```markdown
- 2012\. A great year!
- I think 2009 was second best.
```

--------------------------------

### Markdown Ordered Lists

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Details the creation of ordered lists in markdown. Items are denoted by numbers followed by periods. The numbering does not need to be sequential, but the list must start with '1.'. Indentation can be used to create nested lists.

```markdown
1. First item
2. Second item
   1. Indented item
   1. Indented item
3. Third item
```

--------------------------------

### Strongly Emphasise Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use double asterisks (**) or underscores (__) before and after text to strongly emphasize it (bold). This is recommended by GDS Style Guide for referring to text from interfaces.

```markdown
This text is **strongly emphasised**.
```

```markdown
This text is __strongly emphasised__.
```

--------------------------------

### Emphasise Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use single asterisks (*) or underscores (_) before and after text to emphasize it (italicize). Note that GDS Style Guide recommends against italics, preferring single quotation marks.

```markdown
This text is *emphasised*.
```

```markdown
This text is _emphasised_.
```

--------------------------------

### Release a New Version of the Plugin

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/README.md

This command initiates the process of releasing a new version of the plugin. It automates versioning, publishing to NPM, creating Git tags, and generating release notes. This requires appropriate permissions to publish to the '@x-govuk' organization.

```bash
npm run release
```

--------------------------------

### Configure Eleventy for Subpath Hosting with Environment Variables (JavaScript)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/hosting.md

This JavaScript configuration dynamically sets the `pathPrefix` based on the `GITHUB_ACTIONS` environment variable. It allows for different configurations when running locally versus when deployed via GitHub Actions, ensuring the site works correctly at the root or a subpath. The `govukEleventyPlugin` is registered.

```javascript
import process from 'node:process'

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

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

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    pathPrefix: process.env.GITHUB_ACTIONS ? '/api-docs/' : '/'
  }
};

```

--------------------------------

### Post Layout Configuration in YAML

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Defines the front matter for a blog post or news item using the 'post' layout. Supports metadata like title, description, date, author, image, and tags.

```yaml
---
layout: post
title: Announcing Version 2.0
description: Major improvements to performance and new features.
date: 2024-01-15
modified: 2024-01-20
author:
  - name: Jane Smith
    url: https://example.com/jane
  - name: John Doe
    url: https://example.com/john
image:
  src: /assets/v2-announcement.jpg
  alt: Screenshot of the new dashboard interface
  caption: The redesigned dashboard in version 2.0
  opengraphImage: true
tags:
  - release
  - features
  - performance
showPagination: true
---

We're excited to announce the release of version 2.0 of our API.

## What's New

### Improved Performance

Response times are now 50% faster thanks to our new caching layer.

### New Endpoints

We've added several new endpoints for managing user preferences.

## Migration Guide

Existing users can upgrade by following our [migration guide](/guides/v2-migration).

```

--------------------------------

### Markdown Horizontal Rules

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Shows how to create a horizontal rule using three or more asterisks, dashes, or underscores on a line by themselves.

```markdown
***
---
___
```

--------------------------------

### Highlight Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use double equal signs (==) before and after text to highlight it. This draws attention to specific words or phrases.

```markdown
I need to highlight these ==important words==.
```

--------------------------------

### Configure Front Matter Options with GOV.UK Eleventy Plugin

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Defines common front matter options supported by all layouts for customizing page appearance and metadata. Key options include `layout` (specifying the template type), `title` (for the page title), `description` (for meta description and intro text), and `caption` (for a section name above the title).

```yaml
---
# Required
layout: page                    # Layout to use: page, post, collection, product, sub-navigation
title: Page Title               # Page title (appears in browser and navigation)

# Optional - Content
description: Page description   # Meta description and intro text
caption: Section Name           # Caption above the title

```

--------------------------------

### Markdown Headings

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Illustrates how to create headings of different levels (1-6) using the '#' symbol. The number of '#' symbols corresponds to the heading level.

```markdown
# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
```

--------------------------------

### Create Superscript Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use a single caret symbol (^) before and after characters to create superscript text. This is often used in mathematical expressions.

```markdown
X^2^
```

--------------------------------

### Apply Product Layout in YAML Front Matter

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/product.md

Demonstrates how to set the 'product' layout for a page in Eleventy using YAML front matter. This is the primary method to enable the product page layout.

```yaml
---
layout: product
title: Page title
---

Page content
```

--------------------------------

### Create Subscript Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use a single tilde symbol (~) before and after characters to create subscript text. This is commonly used in chemical formulas.

```markdown
H~2~O
```

--------------------------------

### Configure Eleventy for Subpath Hosting (JavaScript)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/hosting.md

This JavaScript configuration sets the `pathPrefix` option in Eleventy to handle sites hosted on a subpath, ensuring correct navigation and asset loading. It's useful when deploying to locations like `https://<username>.github.io/<reponame>`. The `govukEleventyPlugin` is also registered.

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

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

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    pathPrefix: "/api-docs/"
  }
};

```

--------------------------------

### Mark Inserted Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use double plus signs (++) before and after text to indicate it as inserted. This can be combined with the syntax for deleted text.

```markdown
I need to ~~remove~~ ++insert++ a word.
```

--------------------------------

### Basic Page Layout Configuration

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Defines front matter for a page using the 'page' layout in Eleventy. It specifies layout, title, description, order, pagination settings, and optional aside and related content sections.

```yaml
---
layout: page
title: Getting Started
description: Learn how to set up and configure the service.
order: 1
showPagination: true
aside:
  title: Related Links
  content: |
    - [API Reference](/api)
    - [Examples](/examples)
related:
  title: Related content
  items:
    - text: Configuration Guide
      href: /guides/configuration
    - text: Troubleshooting
      href: /guides/troubleshooting
---

## Introduction

This guide will help you get started with our API service.

## Prerequisites

Before you begin, ensure you have:
- An API key
- Node.js v22 or later installed

## Quick Start

1. Install the client library
2. Configure your credentials
3. Make your first API call

```

--------------------------------

### Mark Deleted Text in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Use double tildes (~~) before and after text to indicate it as deleted or a mistake. This is useful for showing revisions or corrections.

```markdown
~~The world is flat.~~ We now know that the world is round.
```

--------------------------------

### Comprehensive Eleventy Plugin Configuration

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Configures the GOV.UK Eleventy Plugin with a wide range of options, including site URL, header, service navigation, footer, and various template features like search, sitemaps, and RSS feeds. It also includes markdown rendering options.

```javascript
// eleventy.config.js
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    // Site URL (required for canonical URLs and Open Graph)
    url: 'https://my-docs-site.example.com',

    // Page title suffix (replaces default 'GOV.UK')
    titleSuffix: 'My Documentation',

    // Home page navigation key
    homeKey: 'Home',

    // Theme color for browser
    themeColor: '#0b0c0c',

    // Open Graph default image
    opengraphImageUrl: '/assets/og-image.png',

    // Header configuration
    header: {
      logotype: {
        text: 'My Organisation'  // Replace GOV.UK logo with text
      },
      productName: 'API Documentation',
      phaseBanner: {
        tag: { text: 'Beta' },
        html: 'This is a new service. <a class="govuk-link" href="/feedback">Give feedback</a>.'
      },
      search: {
        indexPath: '/search-index.json',
        sitemapPath: '/sitemap'
      }
    },

    // Service navigation
    serviceNavigation: {
      navigation: [{
        text: 'API Reference',
        href: '/api'
      }, {
        text: 'Guides',
        href: '/guides'
      }]
    },

    // Footer configuration
    footer: {
      contentLicence: {
        html: 'Licensed under <a class="govuk-footer__link" href="/licence">MIT Licence</a>'
      },
      copyright: {
        text: '© My Organisation 2024'
      }
    },

    // Template features
    templates: {
      error404: true,           // Enable 404 page
      sitemap: true,            // Enable sitemap
      searchIndex: true,        // Enable search index
      feed: {                   // Enable RSS feed
        collection: 'post',
        size: 20,
        permalink: '/feed.xml'
      },
      tags: {                   // Enable tag pages
        permalink: '/tags',
        title: 'Topics'
      }
    },

    // Markdown options
    markdown: {
      headingPermalinks: true,
      headingsStartWith: 'xl',
      govspeak: true,
      calvert: true
    }
  })

  return {
    dir: { input: 'docs' }
  }
}
```

--------------------------------

### Markdown Blockquotes

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Explains how to create blockquotes by prefixing text with '>'. This includes single-paragraph and multi-paragraph blockquotes, with blank lines between paragraphs also prefixed by '>'.

```markdown
> Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.
```

```markdown
> Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.
>
> Indeed, it has been said that democracy is the worst form of government except all those other forms that have been tried from time to time.
```

--------------------------------

### Collection Layout Configuration in YAML

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Configures a paginated list of pages using the 'collection' layout, suitable for blog indexes or document listings. Specifies data source, items per page, and order.

```yaml
---
layout: collection
title: Blog
description: Latest news and updates from our team.
paginationHeading: Recent Posts
pagination:
  data: collections.post
  size: 10
  reverse: true
---

Welcome to our blog. Here you'll find the latest updates, tutorials, and announcements.

```

--------------------------------

### Format Code Spans in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Enclose words or phrases in backticks (`) to format them as inline code. This is useful for commands or variable names within a sentence.

```markdown
At the command prompt, type `npm install`.
```

--------------------------------

### Configure Post Pagination - YAML

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/post.md

Shows how to enable previous and next post pagination links by setting 'showPagination: true' in the front matter. Posts are ordered by 'title' by default, but can be customized with the 'order' option.

```yaml
---
layout: post
title: Second post title
order: 2
---

This is the second post
```

--------------------------------

### Use Page Layout

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/page.md

Demonstrates how to apply the 'page' layout to an Nunjucks file. This is the primary method for utilizing the flexible page structure.

```yaml
---
layout: page
title: Page title
---

Page content
```

--------------------------------

### Govspeak Warning Callout Formatting

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Formats a word or phrase as a warning callout using the % delimiter in Govspeak markdown. This is used to highlight important warnings or cautionary information.

```markdown
%You can be fined up to £5,000 if you do not register.%

```

--------------------------------

### Govspeak Information Callout Formatting

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Formats a word or phrase as an information callout using the ^ delimiter in Govspeak markdown. This is used to draw attention to specific pieces of information.

```markdown
^The water in the mouth of a blue whale weighs more than its body.^

```

--------------------------------

### Enable Pagination in Page Layout

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/page.md

Shows how to enable previous and next page links within the 'page' layout using front matter. Pages are ordered by 'title' by default, but a custom 'order' option can be specified.

```yaml
---
layout: page
title: Second page title
order: 2
---

This is the second page
```

--------------------------------

### Configure Header with Phase Banner - JavaScript

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/options.md

This JavaScript code snippet demonstrates how to configure the header component within the GOVUK Eleventy Plugin. It specifically shows how to add a product name and a phase banner with custom text and a link.

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    header: {
      productName: 'Apply for a juggling licence',
      phaseBanner: {
        tag: {
          text: 'Alpha'
        },
        html: 'This is a new service. Help us improve it and <a class="govuk-link" href="/feedback">give your feedback</a>.'
      }
    }
  })
}
```

--------------------------------

### Configure Search Index with GOV.UK Eleventy Plugin

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Enables site search by configuring an automatically generated JSON search index. This involves setting the `indexPath` and optionally `sitemapPath` within the plugin's header or service navigation options. The `searchIndex` template option controls the permalink for the generated index file.

```javascript
// eleventy.config.js
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    header: {
      productName: 'API Docs',
      search: {
        indexPath: '/search-index.json',
        sitemapPath: '/sitemap',
        label: 'Search documentation'
      }
    },
    // Or place search in service navigation
    serviceNavigation: {
      navigation: [{ text: 'Home', href: '/' }],
      search: {
        indexPath: '/search-index.json',
        sitemapPath: '/sitemap'
      }
    },
    templates: {
      searchIndex: {
        permalink: '/search-index.json'  // Default path
      }
    }
  })

  return { dir: { input: 'docs' } }
}
```

--------------------------------

### Customize GOV.UK Frontend Settings with SCSS

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/upgrading/6-to-7.md

This SCSS code demonstrates how to customize GOV.UK Frontend settings, such as font family, brand color, and link colors, using the `@use` directive. It also shows how to import components from the GOV.UK Eleventy Plugin.

```scss
// Use GOV.UK Frontend
$_font-family: system-ui, sans-serif;
@use "pkg:govuk-frontend/dist/govuk" with (
  $govuk-font-family: $_font-family,
  $govuk-brand-colour: #8822aa,
  $govuk-link-colour: #660088,
  $govuk-link-hover-colour: #440066,
  $govuk-link-visited-colour: #333366,
  $govuk-page-width: 1100px
);

// Use GOV.UK Eleventy Plugin components
@use "pkg:@x-govuk/govuk-eleventy-plugin";
```

--------------------------------

### Configure Header Product Name in Eleventy

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/options.md

This snippet shows how to add a product name to the GOV.UK header using the `govukEleventyPlugin`. It requires the `@x-govuk/govuk-eleventy-plugin` package and modifies the `header` configuration object within the plugin options.

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    header: {
      productName: 'Apply for a juggling licence',
    }
  })
}
```

--------------------------------

### Add Syntax Highlighting to Code Blocks in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Specify the programming language after the opening backticks in a fenced code block to enable syntax highlighting. This improves readability for code snippets.

```markdown
```json
{
  "firstName": "William",
  "lastName": "Pitt",
  "age": 24
}
```
```

--------------------------------

### Sub-Navigation Layout Configuration in YAML

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Defines front matter for a page using the 'sub-navigation' layout, which provides side navigation for related content. Includes title, description, section key, and order.

```yaml
---
layout: sub-navigation
title: API Endpoints
description: Complete reference for all available API endpoints.
sectionKey: API Reference
order: 1
showPagination: true
---

## Overview

This section documents all available API endpoints.

## Authentication

All endpoints require authentication via API key.

```

--------------------------------

### Add Table of Contents in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

To include a table of contents on a page, insert the [[toc]] tag in Markdown where you want the list to appear. This is a simple tag to enable automatic content indexing.

```markdown
[[toc]]
```

--------------------------------

### Use Post Layout - YAML

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/layouts/post.md

Demonstrates how to apply the 'post' layout to a page using YAML front matter. This is the primary method for enabling the post layout functionality.

```yaml
---
layout: post
title: Page title
---

Page content
```

--------------------------------

### Configure GOV.UK Frontend Assets Path for Subpath (SCSS)

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/hosting.md

This SCSS snippet demonstrates how to configure the `$govuk-assets-path` variable when overriding default GOV.UK Frontend styles. It ensures that assets are correctly referenced when the Eleventy site is hosted on a subpath, prepending the sub-folder name to the asset path.

```scss
@use "pkg:govuk-frontend/dist/govuk" with (
  $govuk-assets-path: "/api-docs/assets/"
);

```

--------------------------------

### Govspeak Address Formatting

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Formats a block of text as an address using the $A delimiter in Govspeak markdown. This is used for displaying addresses in a distinct box. Ensure no bold formatting is used for the address title.

```markdown
$A
HM Revenue and Customs
Bradford
BD98 1YY
$A
```

--------------------------------

### Align Table Columns in Markdown

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/example/markdown.md

Illustrates how to control text alignment within table columns (left, center, right) by adding colons to the hyphens in the header row. This improves table readability.

```markdown
| Syntax    | Description |   Test Text |
| :-------- | :---------: | ----------: |
| Header    |    Title    | Here’s this |
| Paragraph |    Text     |    And more |
```

--------------------------------

### Configure Plugin Options in Eleventy

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/features.md

This JavaScript code demonstrates how to register and configure the GOV.UK Eleventy Plugin. It shows how to disable the default 404 error page and sitemap by setting their respective options to 'false'. The configuration also sets the template engines and input directory for Eleventy.

```javascript
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  // Register and configure the plugin
  eleventyConfig.addPlugin(govukEleventyPlugin, {
    templates: {
      error404: false,
      sitemap: false
    }
  })

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    dir: {
      input: 'docs',
    }
  }
};
```

--------------------------------

### Basic Eleventy Plugin Registration

Source: https://context7.com/x-govuk/govuk-eleventy-plugin/llms.txt

Registers the GOV.UK Eleventy Plugin with default options in the Eleventy configuration file. It sets up the necessary template engines and input directory.

```javascript
// eleventy.config.js
import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

export default function(eleventyConfig) {
  // Register the plugin with default options
  eleventyConfig.addPlugin(govukEleventyPlugin)

  return {
    dataTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    markdownTemplateEngine: 'njk',
    dir: {
      input: 'docs',
    }
  }
}
```

--------------------------------

### Customise GOV.UK Frontend Settings with SCSS Variables

Source: https://github.com/x-govuk/govuk-eleventy-plugin/blob/main/docs/get-started/upgrading/5-to-6.md

Allows customisation of GOV.UK Frontend settings by defining SCSS variables in a settings file. This method replaces older configuration options like 'brandColour' and 'fontFamily'. The settings file can be placed at `/sass/_settings.scss` or a custom path defined by `scssSettingsPath`.

```scss
$govuk-brand-colour: #2288aa;
$govuk-font-family: system-ui, sans-serif;
```
Tokens:
Raw