Markdown extension library for Government editors
Clone or download
Latest commit b9bc0d6 Mar 23, 2018

Govspeak is our markdown-derived mark-up language.


Install the gem

gem install govspeak

or add it to your Gemfile

gem "govspeak", "~> 3.4.0"

then create a new document

require 'rubygems'
require 'govspeak'

doc = "^Test^"
puts doc.to_html

or alternatively, run it from the command line

$ govspeak "render-me"
$ govspeak --file
$ echo "render-me" | govspeak

options can be passed in through --options as a string of JSON or a file of JSON can be passed in as --options-file options.json.

if installed via bundler prefix commands with bundle exec eg $ bundle exec govspeak "render-me"


In addition to the standard Markdown syntax, we have added our own extensions.


Information callouts

^This is an information callout^

creates a callout with an info (i) icon.

<div role="note" aria-label="Information" class="application-notice info-notice">
  <p>This is an information callout</p>

Warning callouts

%This is a warning callout%

creates a callout with a warning or alert (!) icon

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

Example callout

**Example**: Open the pod bay doors

creates an example box

<div class="example">
  <p><strong>Example:</strong> Open the pod bay doors</p>



@This is a very important message or warning@

highlights the enclosed text in yellow

<h3 role="note" aria-label="Important" class="advisory">
  <span>This is a very important message or warning</span>


The VAT rate is *20%*

creates a large highlight box with optional preamble text and giant text denoted with **

<div class="highlight-answer">
  <p>The VAT rate is <em>20%</em></p>

Statistic headline

Used in HTML publications.

Statistic headlines highlight important numbers in content. Displays a statistic as a large number with a description. The statistic and description must make sense when read aloud. The important number must be wrapped in **.

*13.8bn* years since the big bang

Creates the following:

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

Points of Contact


**Student Finance England**
**Telephone:** 0845 300 50 90
**Minicom:** 0845 604 44 34

creates a contact box

<div class="contact">
    <strong>Student Finance England</strong><br>
    <strong>Telephone:</strong> 0845 300 50 90<br>
    <strong>Minicom:</strong> 0845 604 44 34


Hercules House
Hercules Road
London SE1 7DU

creates an address box

<div class="address">
  <div class="adr org fn">
      Hercules House<br>
      Hercules Road<br>
      London SE1 7DU<br>


[An example form download link]( "Example form")

Something about this form download

creates a file download box

<div class="form-download">
  <p><a href="" title="Example form" rel="external">An example form download link.</a></p>


This is a place

creates a place box

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


This is information

creates an information box

<div class="information">
  <p>This is information</p>

Additional Information

This is additional information

creates an additional information box

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

Call to Action

This is a call to action

creates an additional information box

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


This is a summary

creates a summary box

<div class="summary">
  <p>This is a summary</p>

External Link

x[External Report](

creates a link specified as external

<a href="" rel="external">External Report</a>


Steps can be created similar to an ordered list:

s1. numbers
s2. to the start
s3. of your list

Note that steps need an extra line break after the final step (ie. two full blank lines) or other markdown directly afterwards won't work. If you have a subhead after - add a line break after this.

Legislative Lists

For lists where you want to specify the numbering and have multiple indent levels.

* 1. Item 1
* 2. Item 2
  * a) Item 2a
  * b) Item 2b
    * i. Item 2 b i
    * ii. Item 2 b ii
* 3. Item 3
(to indent, add 2 spaces)

Priority Lists

For lists where you want to specify a number of items to be highlighted as priority.

- Item 1
- Item 2
- Item 3
- Item 4
- Item 5

creates a list with priority items flagged with a class

  <li class="primary-item">Item 1</li>
  <li class="primary-item">Item 2</li>
  <li class="primary-item">Item 3</li>
  <li>Item 4</li>
  <li>Item 5</li>

Devolved content

:england:content goes here:england:
:scotland:content goes here:scotland:
:london:content goes here:london:
:wales:content goes here:wales:
:northern-ireland:content goes here:northern-ireland:
:england-wales:content goes here:england-wales:

will create a box for the specified locality

<div class="devolved-content england">
  <p class="devolved-header">This section applies to England</p>
  <div class="devolved-body">
    <p>content goes here</p>


For when you want a table to be progressively enhanced by Javascript to be rendered as a bar chart.


will be rendered as

<table class="js-barchart-table mc-auto-outdent">

Embedded Content

Embedded content allows authors to reference a supporting item of a document by referencing an id. The details of this content is passed to the publishing application to govspeak at the time of rendering.


To create an attachment callout


with options provided

  attachments: [
      id: 123,
      content_id: "2b4d92f3-f8cd-4284-aaaa-25b3a640d26c",
      title: "Attachment Title",
      url: "",
      order_url: "",
      price: 12.3,
      isbn: "isbn-123",
      attachment?: true,

will output an attachment box

<section class="attachment embedded">
  <div class="attachment-thumb">
    <a href="" aria-hidden="true" class="embedded"><img src="/images/pub-cover.png" alt="Pub cover"></a>
  <div class="attachment-details">
    <h2 class="title">
      <a href="" aria-describedby="attachment-123-accessibility-help">Attachment Title</a>
    <p class="metadata">
      <span class="references">Ref: ISBN <span class="isbn">isbn-123</span></span>
      <a href="" class="order_url" title="Order a copy of the publication">Order a copy</a>(<span class="price">£12.30</span>)

Inline Attachment

Attachments can be linked to inline as well

Details referenced in [embed:attachments:inline:34f6dda0-21b1-4e78-8120-3ff4dcea522d]

with options provided

  attachments: [
      content_id: "34f6dda0-21b1-4e78-8120-3ff4dcea522d",
      title: "My Thorough Study",
      url: "",

will output an attachment within a block of text

<p>Details referenced in <span class="attachment-inline"><a href="">My Thorough Study</a></span></p>

Image Attachments

Attachments can be used to embed an image within the document


with options provided

  attachments: [
      content_id: "45ee0eea-bc53-4f14-81eb-9e75d33c4d5e",
      title: "A lovely landscape",
      url: "",

will output a image section

<figure class="image embedded">
  <div class="img">
    <img src="" alt="A Lovely Landscape">


Links to different documents can be embedded so they change when the documents they reference change.

A link to [embed:link:c636b433-1e5c-46d4-96b0-b5a168fac26c]

with options provided

  links: [
      url: "",
      title: "An excellent website",

will output

<p>A link to <a href="">An excellent website</a></p>



with options provided

  contacts: [
      id: 123,
      content_id: "df62690f-34a0-4840-a7fa-4ef5acc18666",
      title: "Government Digital Service",
      email: "",
      contact_numbers: [
        { label: "helpdesk", number: "+4412345 67890"}

will output

<div id="contact_123" class="contact">
  <div class="content">
    <h3>Government Digital Service</h3>
    <div class="vcard contact-inner">
      <div class="email-url-number">
        <p class="email">
          <span class="type">Email</span>
          <a href="" class="email"></a>
        <p class="tel">
          <span class="type">helpdesk</span>
          +4412345 67890


An accessible way to add button links into content, that can also allow cross domain tracking with Google Analytics

This button component is extended from static for use in govspeak Note: Ideally we'd use the original component directly but this currently isnt possible

You must use the link syntax within the button tags.


To get the most basic button.


which outputs

<a role="button" class="button" href="">

To turn a button into a 'Start now' button, you can pass start to the button tag.

{button start}[Start Now]({/button}

which outputs

<a role="button" class="button button-start" href="">
  Start Now

You can pass a Google Analytics tracking id which will send page views to another domain, this is used to help services understand the start of their users journeys.

{button start cross-domain-tracking:UA-XXXXXX-Y}
  [Start Now](

which outputs

  class="button button-start"
  Start Now