Govspeak Markdown ·

Govspeak Markdown extensions for Marked.

Requirements

Node.js v18 or later.

Installation

npm install @x-govuk/marked-govspeak

Usage

import { marked } from 'marked'
import govspeak from '@x-govuk/marked-govspeak'

marked.use(govspeak())

When you call marked, the generated HTML will include the classes to style the Govspeak Markdown extensions. For example:

marked('%This is a warning callout%')

will output:

<div class="govspeak-warning-callout" role="note" aria-label="Warning">
  <p>This is a warning callout</p>
</div>

To enable the styling you will need to add the following to your Sass file:

@import "node_modules/@x-govuk/marked-govspeak/govspeak/all";

Differences from the Govspeak Ruby gem

Unlike the Govspeak gem, this package is not used to publish any part of GOV.UK. For that reason, it doesn’t support the following extensions:

• bar charts
• cross domain tracking on buttons
• embedded content and attachment links
• tables that use Kramdown syntax

This package also provides its own set of CSS styles, based on those used by GOV.UK Publishing Components.

The class names used also differ, each prefixed with govspeak-. Therefore a govspeak or gem-c-govspeak class is not needed on any parent container.

Using original Govspeak gem classes

If you wish to generate class names that match those from the Govspeak Ruby gem, you can pass the govspeakGemCompatibility option to marked. For example:

import { marked } from 'marked'
import govspeak from '@x-govuk/marked-govspeak'

marked.use(govspeak({
  govspeakGemCompatibility: true
}))

marked('%This is a warning callout%')

will output:

<div class="application-notice help-notice" role="note" aria-label="Warning">
  <p>This is a warning callout</p>
</div>

[!NOTE]
You will need to provide your own styles if you use this option.

Supported extensions

Address

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

<div class="govspeak-address">
  <div class="adr org fn">
    <p>
      HM Revenue and Customs<br />
      Bradford<br />
      BD98 1YY
    </p>
  </div>
</div>

Buttons

An accessible way to add button links into content.

Default button

{button}[Continue](https://gov.uk/random){/button}

<a class="govuk-button" href="https://gov.uk/random" role="button">
  Continue
</a>

Start button

To turn a button into a ‘Start now’ button, you can pass start to the button tag:

{button start}[Start Now](https://gov.uk/random){/button}

<a
  class="govuk-button govuk-button--start"
  href="https://gov.uk/random"
  role="button"
>
  Start Now
  <svg
    class="govuk-button__start-icon"
    xmlns="http://www.w3.org/2000/svg"
    width="17.5"
    height="19"
    viewBox="0 0 33 40"
    role="presentation"
    focusable="false"
  >
    <path fill="currentColor" d="M0 0h13l20 20-20 20H0l20-20z"></path>
  </svg>
</a>

Callouts

Information callout

^This is useful information that’s worth knowing.^

<div class="govspeak-information-callout" role="note" aria-label="Information">
  <p>This is useful information that’s worth knowing.</p>
</div>

Warning callout

%You will be fined or put in prison if you don’t do this thing.%

<div class="govspeak-warning-callout" role="note" aria-label="Warning">
  <p>You will be fined or put in prison if you don’t do this thing.</p>
</div>

Example callout

$E
Open the pod bay doors.
$E

<div class="govspeak-example">
  <p>Open the pod bay doors.</p>
</div>

Call to action

$CTA
This is a call to action
$CTA

<div class="govspeak-call-to-action">
  <p>This is a call to action</p>
</div>

Contact

$C
Financial Conduct Authority
<[email protected]>
Telephone: 0800 111 6768
Monday to Friday, 8am to 6pm
Saturday, 9am to 1pm
[Find out about call charges](/call-charges)
$C

<div class="govspeak-contact">
  <p>
    Financial Conduct Authority<br />
    <a href="mailto:[email protected]">[email protected]</a
    ><br />
    Telephone: 0800 111 6768<br />
    Monday to Friday, 8am to 6pm<br />
    Saturday, 9am to 1pm<br />
    <a href="/call-charges">Find out about call charges</a>
  </p>
</div>

Download link

$D
[Download ‘Jobcentre Plus form for employment’ (PDF, 43KB)](/example.pdf)
$D

<div class="govspeak-form-download">
  <p>
    <a href="/example.pdf"
      >Download ‘Jobcentre Plus form for employment’ (PDF, 43KB)</a
    >
  </p>
</div>

Place

$P
This is a place.
$P

<div class="govspeak-place">
  <p>This is a place.</p>
</div>

Information

$I
This is information.
$I

<div class="govspeak-information">
  <p>This is information.</p>
</div>

Statistic headline

{stat-headline}
_13.8bn_ years since the big bang
{/stat-headline}

<div class="govspeak-stat-headline">
  <p><em>13.8bn</em> years since the big bang</p>
</div>

Steps

s1. Add numbers.
s2. Check numbers.
s3. Love numbers.

<ol class="govuk-steps">
  <li>Add numbers.</li>
  <li>Check numbers.</li>
  <li>Love numbers.</li>
</ol>

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.