Skip to content

Convert Markdown into GOV.UK Frontend-compliant HTML.

License

Notifications You must be signed in to change notification settings

x-govuk/govuk-markdown

Folders and files

NameName
Last commit message
Last commit date

Latest commit

79daaae · Dec 27, 2024

History

89 Commits
Dec 9, 2023
Nov 14, 2024
Feb 5, 2024
Mar 4, 2022
Mar 4, 2022
May 19, 2023
Dec 15, 2023
Dec 19, 2023
Mar 19, 2022
Dec 15, 2023
Nov 14, 2024
Nov 14, 2024
Dec 27, 2024
Nov 14, 2024

Repository files navigation

GOV.UK Markdown · test

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.