GOV.UK Markdown renderer

This Ruby gem converts Markdown into GOV.UK Frontend-compliant HTML. It's an extension on the default Redcarpet renderer.

Don't confuse this gem with govspeak, which is a Markdown dialect specifically built for the GOV.UK publishing system (www.gov.uk).

Note that this gem supports GOV.UK Design System version 5.3.0.

Add this line to your application's Gemfile:

gem 'govuk_markdown'

GovukMarkdown.render(markdown)

For example:

GovukMarkdown.render("[A link](/foo)")

Will output:

<p class="govuk-body-m">
  <a href="/foo" class="govuk-link">A link</a>
</p>

By default, H1 headings will be set to XL. You can override the start heading size, for example if you want to start with size L instead.

All subsequent headings i.e. H2, H3, will be sized correctly according to the start heading size.

Values can be "xl", "l", "m" and "s".

To specify the start heading size for your markdown content, add the below option into your GovukMarkdown.render() method:

GovukMarkdown.render(markdown, headings_start_with: "l")

To add inset text to your markdown document, use the following tags:

{inset-text}Text to be inset goes here{/inset-text}

The renderer also handles multi-line text as well as multiple paragraphs inside the tags:

{inset-text}
  Text to be
  inset goes
  here
{/inset-text}

To add the details component to your markdown, use the following tags:

{details} Find out about the fox and the dog. Whilst the fox is quick and brown, the dog is lazy.{/details}

The first sentence is rendered as the details summary text. The remaining text is rendered as the details text. The renderer handles multiple paragraphs for the details text.

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

You can regenerate the example HTML file from Markdown using bundle exec rake generate_example.

Bug reports and pull requests are welcome on GitHub at https://github.com/DfE-digital/govuk-markdown.