{"id":19028639,"url":"https://github.com/x-govuk/markdown-it-govuk","last_synced_at":"2026-03-06T19:13:50.446Z","repository":{"id":37975179,"uuid":"470299391","full_name":"x-govuk/markdown-it-govuk","owner":"x-govuk","description":"Plugin for markdown-it to convert Markdown into GOV.UK Frontend-compliant HTML","archived":false,"fork":false,"pushed_at":"2026-02-14T18:55:16.000Z","size":815,"stargazers_count":3,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-15T02:57:31.637Z","etag":null,"topics":["govuk","markdown","markdown-it","markdown-it-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/x-govuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-15T19:14:38.000Z","updated_at":"2026-02-14T18:27:49.000Z","dependencies_parsed_at":"2023-12-15T22:25:22.315Z","dependency_job_id":"6f948c81-e74d-45ce-a790-48afab729680","html_url":"https://github.com/x-govuk/markdown-it-govuk","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.05555555555555558,"last_synced_commit":"c4d8d8144b9ee30bc96b49e20188d6f9a7ff9a44"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/x-govuk/markdown-it-govuk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-govuk%2Fmarkdown-it-govuk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-govuk%2Fmarkdown-it-govuk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-govuk%2Fmarkdown-it-govuk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-govuk%2Fmarkdown-it-govuk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/x-govuk","download_url":"https://codeload.github.com/x-govuk/markdown-it-govuk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-govuk%2Fmarkdown-it-govuk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30192660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["govuk","markdown","markdown-it","markdown-it-plugin"],"created_at":"2024-11-08T21:11:47.648Z","updated_at":"2026-03-06T19:13:50.435Z","avatar_url":"https://github.com/x-govuk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# markdown-it-govuk · [![test](https://github.com/x-govuk/markdown-it-govuk/actions/workflows/test.yml/badge.svg)](https://github.com/x-govuk/markdown-it-govuk/actions/workflows/test.yml)\n\nPlugin for [markdown-it](https://github.com/markdown-it/markdown-it) to convert Markdown into GOV.UK Frontend-compliant HTML, inspired by the [`govuk_markdown`](https://github.com/DFE-Digital/govuk_markdown) and [govspeak](https://github.com/alphagov/govspeak) Ruby gems.\n\nIf you are using the [marked](https://marked.js.org/) parser, use [`govuk-markdown`](https://github.com/x-govuk/govuk-markdown).\n\n## Requirements\n\nNode.js v22 or later.\n\n## Installation\n\n`npm install markdown-it-govuk --save`\n\n## Usage\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk)\n```\n\nThe generated HTML will include the classes from GOV.UK Frontend. For example:\n\n```js\nmd.render('[A link](/foo)')\n```\n\nWill output:\n\n```html\n\u003cp class=\"govuk-body\"\u003e\u003ca class=\"govuk-link\" href=\"/foo\"\u003eA link\u003c/a\u003e\u003c/p\u003e\n```\n\n### Code highlighting\n\nFenced code blocks can he highlighted using the supplied `highlight` function:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\nimport highlight from 'markdown-it-govuk/highlight'\n\nconst md = markdownit({\n  highlight\n})\n\nmd.use(markdownitGovuk)\n```\n\nFor example:\n\n````js\nmd.render('```js\\nconsole.log(\\'Hello, World!\\')\\n```')\n````\n\nWill output:\n\n```html\n\u003cpre class=\"app-code app-code--block\" tabindex=\"0\"\u003e\n  \u003ccode class=\"app-code__language--js\"\u003e\n    \u003cspan class=\"app-code__variable\"\u003econsole\u003c/span\u003e.\u003cspan class=\"app-code__title\"\u003elog\u003c/span\u003e(\u003cspan class=\"app-code__string\"\u003e'Hello, World!'\u003c/span\u003e)\n  \u003c/code\u003e\n\u003c/pre\u003e\n```\n\nTo provide styling for inline and block code, add the following to your Sass file:\n\n```scss\n@import \"markdown-it-govuk/highlight\";\n```\n\nor using the Sass module system and `pkg:` importing:\n\n```scss\n@forward \"pkg:markdown-it-govuk/highlight\";\n```\n\nThese styles rely on `govuk-frontend`, so make sure you have this installed as a dependency in your project.\n\n## Options\n\n| Name                | Type               | Description                                                                                                                                                                                                                                                                                           |\n| ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `headingsStartWith` | `string`           | Heading size to use for the top-level heading (`xl` or `l`). Default is `l`.                                                                                                                                                                                                                          |\n| `brand`             | `string`           | Use either `'govuk'` or `'nhsuk'` namespaced class names. Default is `'govuk'`.                                                                                                                                                                                                                       |\n| `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`. |\n| `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`.      |\n\n### Heading sizes\n\nHeadings start with `govuk-heading-l` for an `\u003ch1\u003e`, `govuk-heading-m` for an `\u003ch2\u003e` 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.\n\nTo start pages with `govuk-heading-xl` for an `\u003ch1\u003e`, `govuk-heading-l` for an `\u003ch2\u003e`, and so on, set the `headingsStartWith` option to `xl`:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  headingsStartWith: 'xl'\n})\n\nmd.render('# Heading\\n## Heading 2')\n```\n\nWill output:\n\n```html\n\u003ch1 class=\"govuk-heading-xl\"\u003eHeading 1\u003c/h1\u003e\n\u003ch2 class=\"govuk-heading-l\"\u003eHeading 2\u003c/h2\u003e\n```\n\n### Typographic improvements\n\nAlongside 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.\n\nFor example:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  calvert: ['fractions', 'mathematical']\n})\n\nmd.render('1/2 x 1/2 = 1/4')\n```\n\nWill output the following text, with the common fractions and correct multiplication symbol:\n\n```html\n\u003cp class=\"govuk-body\"\u003e½ × ½ = ¼\u003c/p\u003e\n```\n\n### Govspeak\n\nYou can enable support for some [Govspeak](https://govspeak-preview.publishing.service.gov.uk/guide) markdown extensions by using the `govspeak` option.\n\nThis plugin supports the following extensions:\n\n- `address`\n- `blockquote`\n- `example-callout`\n- `information-callout`\n- `warning-callout`\n\nYou 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.\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: true\n})\n```\n\nTo provide styling for govspeak extensions, add the following to your Sass file:\n\n```scss\n@import \"markdown-it-govuk/govspeak\";\n```\n\nor using the Sass module system and `pkg:` importing:\n\n```scss\n@forward \"pkg:markdown-it-govuk/govspeak\";\n```\n\nThese styles rely on `govuk-frontend`, so make sure you have this installed as a dependency in your project.\n\n#### Address\n\nFor example:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: ['address']\n})\n\nmd.render(`$A\nHM Revenue and Customs\nBradford\nBD98 1YY\n$A`)\n```\n\nWill output:\n\n```html\n\u003cdiv data-govspeak=\"address\"\u003e\n  \u003cp class=\"govuk-body\"\u003eHM Revenue and Customs\u003cbr\u003e\nBradford\u003cbr\u003e\nBD98 1YY\u003c/p\u003e\n\u003c/div\u003e\n```\n\n#### Blockquote\n\nFor example:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: ['blockquote']\n})\n\nmd.render(`\u003e Some text with a blockquote`)\n```\n\nWill output:\n\n```html\n\u003cblockquote data-govspeak=\"blockquote\"\u003e\n  \u003cp class=\"govuk-body\"\u003eSome text with a blockquote\u003c/p\u003e\n\u003c/blockquote\u003e\n```\n\n#### Example callout\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: ['example-callout']\n})\n\nmd.render(`$E\n**Example callout**\nSome text with an example callout\n$E`)\n```\n\nWill output:\n\n```html\n\u003cdiv data-govspeak=\"example-callout\"\u003e\n  \u003cp class=\"govuk-body\"\u003e\n    \u003cstrong\u003eExample callout\u003c/strong\u003e\n    Some text with an example callout\u003c/p\u003e\n\u003c/div\u003e\n```\n\n#### Information callout\n\nFor example:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: ['information-callout']\n})\n\nmd.render('^ Some text with an information callout ^')\n```\n\nWill output:\n\n```html\n\u003cdiv data-govspeak=\"information-callout\" role=\"note\" aria-label=\"Information\"\u003e\n  \u003cp class=\"govuk-body\"\u003eSome text with an information callout\u003c/p\u003e\n\u003c/div\u003e\n```\n\n#### Warning callout\n\nFor example:\n\n```js\nimport markdownit from 'markdown-it'\nimport markdownitGovuk from 'markdown-it-govuk'\n\nconst md = markdownit.use(markdownitGovuk, {\n  govspeak: ['warning-callout']\n})\n\nmd.render('% Some text with a warning callout %')\n```\n\nWill output:\n\n```html\n\u003cdiv data-govspeak=\"warning-callout\" role=\"note\" aria-label=\"Warning\"\u003e\n  \u003cp class=\"nhsuk-body\"\u003eSome text with a warning callout\u003c/p\u003e\n\u003c/div\u003e\n```\n\n## Releasing a new version\n\n`npm run release`\n\nThis 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.\n\n\u003e [!NOTE]\n\u003e Releasing a new version requires permission to publish packages to the `@x-govuk` organisation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-govuk%2Fmarkdown-it-govuk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx-govuk%2Fmarkdown-it-govuk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-govuk%2Fmarkdown-it-govuk/lists"}