https://github.com/x-govuk/marked-govspeak
Govspeak Markdown extensions for Marked.
https://github.com/x-govuk/marked-govspeak
govspeak govuk markdown marked
Last synced: 9 months ago
JSON representation
Govspeak Markdown extensions for Marked.
- Host: GitHub
- URL: https://github.com/x-govuk/marked-govspeak
- Owner: x-govuk
- License: mit
- Created: 2022-03-08T01:54:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-02-01T02:27:44.000Z (over 1 year ago)
- Last Synced: 2025-08-16T20:57:33.645Z (11 months ago)
- Topics: govspeak, govuk, markdown, marked
- Language: JavaScript
- Homepage:
- Size: 630 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Govspeak Markdown · [](https://github.com/x-govuk/marked-govspeak/actions/workflows/test.yml)
[Govspeak](https://github.com/alphagov/govspeak) Markdown extensions for [Marked](https://github.com/markedjs/marked).
## Requirements
Node.js v18 or later.
## Installation
```shell
npm install @x-govuk/marked-govspeak
```
## Usage
```js
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:
```js
marked('%This is a warning callout%')
```
will output:
```html
This is a warning callout
```
To enable the styling you will need to add the following to your Sass file:
```scss
@import "node_modules/@x-govuk/marked-govspeak/govspeak/all";
```
## Differences from the Govspeak Ruby gem
Unlike [the Govspeak gem](https://github.com/alphagov/govspeak), 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](https://github.com/alphagov/govuk_publishing_components/tree/main/app/assets/stylesheets/govuk_publishing_components/components/govspeak).
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:
```js
import { marked } from 'marked'
import govspeak from '@x-govuk/marked-govspeak'
marked.use(govspeak({
govspeakGemCompatibility: true
}))
marked('%This is a warning callout%')
```
will output:
```html
This is a warning callout
```
> [!NOTE]\
> You will need to provide your own styles if you use this option.
## Supported extensions
### Address
```md
$A
HM Revenue and Customs
Bradford
BD98 1YY
$A
```
```html
HM Revenue and Customs
Bradford
BD98 1YY
```
### Buttons
An accessible way to add button links into content.
#### Default button
```md
{button}[Continue](https://gov.uk/random){/button}
```
```html
Continue
```
#### Start button
To turn a button into a [‘Start now’ button](https://design-system.service.gov.uk/components/button/#start-buttons), you can pass `start` to the button tag:
```md
{button start}[Start Now](https://gov.uk/random){/button}
```
```html
Start Now
```
### Callouts
#### Information callout
```md
^This is useful information that’s worth knowing.^
```
```html
This is useful information that’s worth knowing.
```
#### Warning callout
```md
%You will be fined or put in prison if you don’t do this thing.%
```
```html
You will be fined or put in prison if you don’t do this thing.
```
#### Example callout
```md
$E
Open the pod bay doors.
$E
```
```html
Open the pod bay doors.
```
### Call to action
```md
$CTA
This is a call to action
$CTA
```
```html
This is a call to action
```
### Contact
```md
$C
Financial Conduct Authority
Telephone: 0800 111 6768
Monday to Friday, 8am to 6pm
Saturday, 9am to 1pm
[Find out about call charges](/call-charges)
$C
```
```html
Financial Conduct Authority
consumer.queries@fca.org.uk
Telephone: 0800 111 6768
Monday to Friday, 8am to 6pm
Saturday, 9am to 1pm
Find out about call charges
```
### Download link
```md
$D
[Download ‘Jobcentre Plus form for employment’ (PDF, 43KB)](/example.pdf)
$D
```
```html
```
### Place
```md
$P
This is a place.
$P
```
```html
This is a place.
```
### Information
```md
$I
This is information.
$I
```
```html
This is information.
```
### Statistic headline
```md
{stat-headline}
_13.8bn_ years since the big bang
{/stat-headline}
```
```html
13.8bn years since the big bang
```
### Steps
```md
s1. Add numbers.
s2. Check numbers.
s3. Love numbers.
```
```html
- Add numbers.
- Check numbers.
- Love numbers.
```
## 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.