Plugin for markdown-it to convert Markdown into GOV.UK Frontend-compliant HTML
npm install markdown-it-govukPlugin for markdown-it to convert Markdown into GOV.UK Frontend-compliant HTML, inspired by the govuk_markdown and govspeak Ruby gems.
If you are using the marked parser, use govuk-markdown.
Node.js v22 or later.
npm install markdown-it-govuk --save
``js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'
const md = markdownit.use(markdownitGovuk)
`
The generated HTML will include the classes from GOV.UK Frontend. For example:
`js`
md.render('A link')
Will output:
`html`
Fenced code blocks can he highlighted using the supplied highlight function:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'
import highlight from 'markdown-it-govuk/highlight'
const md = markdownit({
highlight
})
md.use(markdownitGovuk)
`
For example:
``js`
md.render('js\nconsole.log(\'Hello, World!\')\n`')``
Will output:
`html`
console.log('Hello, World!')
To provide styling for inline and block code, add the following to your Sass file:
`scss`
@import "markdown-it-govuk/highlight";
or using the Sass module system and pkg: importing:
`scss`
@forward "pkg:markdown-it-govuk/highlight";
These styles rely on govuk-frontend, so make sure you have this installed as a dependency in your project.
| Name | Type | Description |
| ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| headingsStartWith | string | Heading size to use for the top-level heading (xl or l). Default is l. |brand
| | string | Use either 'govuk' or 'nhsuk' namespaced class names. Default is 'govuk'. |calvert
| | boolean \| Array | Typographic improvements to enable (alongside those provided by markdown-it’s typographer option). Set this option to true to enable all improvements, or array containing individual improvement sets to include (choose from fractions, guillemets and mathematical). Default is false. |govspeak
| | boolean \| Array | Enable support for Govspeak extensions. Set this option to true to enable all supported extensions, or provide an array containing individual extensions to include (choose from address, blockquote, example-callout, information-callout and warning-callout). Default is false. |
Headings start with govuk-heading-l for an
, govuk-heading-m for an and so on. But change it if your pages feel unbalanced – the heading class you use does not always need to correspond to the heading level.To start pages with
govuk-heading-xl for an , govuk-heading-l for an , and so on, set the headingsStartWith option to xl:`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
headingsStartWith: 'xl'
})
md.render('# Heading\n## Heading 2')
`Will output:
`html
Heading 1
Heading 2
`$3
Alongside typographic replacements provided by markdown-it’s
typographer option, you can enable other glyphs present in Margaret Calvert’s GDS Transport font by using the calvert option.For example:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
calvert: ['fractions', 'mathematical']
})
md.render('1/2 x 1/2 = 1/4')
`Will output the following text, with the common fractions and correct multiplication symbol:
`html
½ × ½ = ¼
`$3
You can enable support for some Govspeak markdown extensions by using the
govspeak option.This plugin supports the following extensions:
-
address
- blockquote
- example-callout
- information-callout
- warning-calloutYou can enable support for all extensions by setting the option to
true, or you can enable support for individual extensions by providing an array containing the names of the extensions you want to use.`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: true
})
`To provide styling for govspeak extensions, add the following to your Sass file:
`scss
@import "markdown-it-govuk/govspeak";
`or using the Sass module system and
pkg: importing:`scss
@forward "pkg:markdown-it-govuk/govspeak";
`These styles rely on
govuk-frontend, so make sure you have this installed as a dependency in your project.#### Address
For example:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: ['address']
})
md.render(
$A)
`Will output:
`html
HM Revenue and Customs
Bradford
BD98 1YY
`#### Blockquote
For example:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: ['blockquote']
})
md.render(
> Some text with a blockquote)
`Will output:
`html
Some text with a blockquote
`#### Example callout
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: ['example-callout']
})
md.render(
$E)
`Will output:
`html
Example callout
Some text with an example callout
`#### Information callout
For example:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: ['information-callout']
})
md.render('^ Some text with an information callout ^')
`Will output:
`html
Some text with an information callout
`#### Warning callout
For example:
`js
import markdownit from 'markdown-it'
import markdownitGovuk from 'markdown-it-govuk'const md = markdownit.use(markdownitGovuk, {
govspeak: ['warning-callout']
})
md.render('% Some text with a warning callout %')
`Will output:
`html
Some text with a warning callout
`Releasing a new version
npm run releaseThis 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.