govuk-markdown

GOV.UK Markdown ·

Convert Markdown into GOV.UK Frontend-compliant HTML. It’s an extension to the marked renderer and is inspired by its Ruby equivalent gem govuk_markdown.

Don’t confuse this package with govspeak, which is a Markdown dialect specifically built for the GOV.UK publishing system.

Requirements

Node.js v18 or later.

Installation

npm install govuk-markdown --save

Usage

const { marked } = require('marked')
const govukMarkdown = require('govuk-markdown')

marked.use(govukMarkdown())

If you are using ES modules, import as follows:

import { marked } from 'marked'
import govukMarkdown from 'govuk-markdown'

marked.use(govukMarkdown())

When you call marked, the generated HTML will include the classes from GOV.UK Frontend. For example:

marked('[A link](/foo)')

Will output:

<p class="govuk-body">
  <a class="govuk-link" href="/foo">A link</a>
</p>

Code highlighting

Block code is highlighted using highlight.js. For example:

marked("```js\nconsole.log('Hello, World!')\n```")

Will output:

<pre class="x-govuk-code x-govuk-code--block" tabindex="0">
  <code class="x-govuk-code__language--js">
    <span class="x-govuk-code__variable">console</span>.<span class="x-govuk-code__title">log</span>(<span class="x-govuk-code__string">'Hello, World!'</span>)
  </code>
</pre>

Additional styles

To enable the styling for inline code, block code and checkboxes in task lists, add the following to your Sass file:

@import "govuk-markdown/x-govuk/all";

Options

In addition to marked’s options, this extension accepts additional values:

Name	Type	Description
headingsStartWith	string	Heading size to use for the top-level heading (xl or l). Default is l.

For example:

const { marked } = require('marked')
const { govukMarkdown } = require('govuk-markdown')

marked.use(govukMarkdown({
  headingsStartWith: 'xl'
}))

marked('# Extra large heading')

Will output:

<h1 class="govuk-heading-xl">Extra large heading</h1>

Testing

npm test

Releasing a new version

npm run release

This command will ask you what version you want to use. It will then publish a new version on NPM, create and push a new git tag and then generate release notes ready for posting on GitHub.

[!NOTE] Releasing a new version requires permission to publish packages to the @x-govuk organisation.