markdown-it-govuk ·
Plugin for markdown-it to convert Markdown into GOV.UK Frontend-compliant HTML, inspired by its Ruby equivalent gem govuk_markdown
. If you are using the marked parser, use govuk-markdown
.
Don’t confuse this package with govspeak, which is a Markdown dialect specifically built for the GOV.UK publishing system (www.gov.uk).
Requirements
Node.js v18 or later.
Installation
npm install markdown-it-govuk --save
Usage
const md = require('markdown-it')
md.use(require('markdown-it-govuk'))
The generated HTML will include the classes from GOV.UK Frontend. For example:
md.render('[A link](/foo)')
Will output:
<p class="govuk-body"><a class="govuk-link" href="/foo">A link</a></p>
Code highlighting
Fenced code blocks can he highlighted using the supplied highlight
function:
const md = require('markdown-it')({
highlight: require('markdown-it/highlight')
})
md.use(require('markdown-it-govuk'))
For example:
md.render('```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>
To provide styling for inline and block code, add the following to your Sass file:
@import "markdown-it-govuk/x-govuk/all";
Options
Name | Type | Description |
---|---|---|
headingsStartWith |
string |
Heading size to use for the top-level heading (xl or l ). Default is l . |
calvert |
boolean | Array |
Typographic improvements to enable (in addition to 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 . |
Heading sizes
Headings start with govuk-heading-l
for an <h1>
, govuk-heading-m
for an <h2>
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 <h1>
, govuk-heading-l
for an <h2>
, and so on, set the headingsStartWith
option to xl
:
md.use(require('markdown-it-govuk'), {
headingsStartWith: 'xl'
})
marked('# Heading\n## Heading 2')
Will output:
<h1 class="govuk-heading-xl">Heading 1</h1>
<h2 class="govuk-heading-l">Heading 2</h2>
Typographic improvements
In addition to the typographic replacements provided by markdown-it’s typographer
option, you can enable a number of other glyphs present in Margaret Calvert’s GDS Transport font using the calvert
option.
For example:
md.use(require('markdown-it-govuk'), {
calvert: ['fractions', 'mathematical']
})
marked('1/2 x 1/2 = 1/4')
Will output the following text, with the common fractions and correct multiplication symbol:
<p class="govuk-body">½ × ½ = ¼</p>
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.