Govspeak is our markdown-derived mark-up language.
Usage
Install the gem
gem install govspeak
or add it to your Gemfile
gem "govspeak"
then create a new document
require 'rubygems'
require 'govspeak'
doc = Govspeak::Document.new "^Test^"
puts doc.to_html
Changes appearing across GOV.UK
Some additional steps or considerations are needed to ensure changes to govspeak cascade across GOV.UK in a holistic way.
Once govspeak has been updated and version incremented then:
- govuk_publishing_components govspeak will also need updating to reflect your most recent change.
- Publishing apps (including but not limited to content-publisher & whitehall) also use govspeak, these apps will need to be released with the new govspeak version present.
Also, consider if: - whitehall needs updating (as custom govspeak changes are present) - govspeak-preview needs updating
Any pages that use govspeak to generate Content will need to republished in order for the new changes to be reflected.
- Data Labs can help identify which pages need updating by submitting a request and #govuk-2ndline can help with republishing
Extensions
In addition to the standard Markdown syntax, we have added our own extensions.
Callouts
Information callouts
^This is an information callout^
creates a callout with an info (i) icon.
```html
This is an information callout
```
Warning callouts
%This is a warning callout%
creates a callout with a warning or alert (!) icon
```html
This is a warning callout
```
Example callout
$E
**Example**: Open the pod bay doors
$E
creates an example box
```html
Example: Open the pod bay doors
```
Highlights
Advisory (DEPRECATED: marked for removal. Use ‘Information callouts’ instead.)
@This is a very important message or warning@
highlights the enclosed text in yellow
```html
This is a very important message or warning
```
Answer (DEPRECATED: marked for removal)
{::highlight-answer}
The VAT rate is *20%*
{:/highlight-answer}
creates a large highlight box with optional preamble text and giant text denoted with **
```html
The VAT rate is 20%
```
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 **.
{stat-headline}
*13.8bn* years since the big bang
{/stat-headline}
Creates the following:
```html
13.8bn years since the big bang
```
Points of Contact
Contact
$C
**Student Finance England**
**Telephone:** 0845 300 50 90
**Minicom:** 0845 604 44 34
$C
creates a contact box
```html
Student Finance England
Telephone: 0845 300 50 90
Minicom: 0845 604 44 34
```
Address
$A
Hercules House
Hercules Road
London SE1 7DU
$A
creates an address box
```html
Hercules House
Hercules Road
London SE1 7DU
```
Downloads
$D
[An example form download link](http://example.com/ "Example form")
Something about this form download
$D
creates a file download box
```html
```
Place
$P
This is a place
$P
creates a place box
```html
This is a place
```
Information
$I
This is information
$I
creates an information box
```html
This is information
```
Additional Information
$AI
This is additional information
$AI
creates an additional information box
```html
This is additional information
```
Call to Action
$CTA
This is a call to action
$CTA
creates an additional information box
```html
This is a call to action
```
Summary
$!
This is a summary
$!
creates a summary box
```html
This is a summary
```
External Link
x[External Report](https://example.com/report)x
creates a link specified as external
html
<a href="https://example.com/report" rel="external">External Report</a>
Steps
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.
$LegislativeList
* 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
$EndLegislativeList
(to indent, add 2 spaces)
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
```html
This section applies to England
content goes here
```
Tables
Tables follow the Kramdown syntax for tables with one addition - table headers can be specified by adding a # at the start of the cell. A table header inside the table head will be given a scope of col; a table header outside will be given a scope of row.
markdown
| |# Column header one |# Column header two |
|---------------|--------------------|--------------------|
|# Row header 1 | Content #1 | Content #2 |
|# Row header 1 | Content #3 | Content #4 |
```html
| Column header one | Column header two | |
|---|---|---|
| Row header 1 | Content #1 | Content #2 |
| Row header 2 | Content #3 | Content #4 |
```
Barcharts
For when you want a table to be progressively enhanced by Javascript to be rendered as a bar chart.
|col|
|---|
|val|
{barchart}
will be rendered as
```html
| col |
|---|
| val |
```
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.
Attachments
Attachments can be be rendered as blocks
[Attachment:file.txt]
with options provided
{
attachments: [
{
id: "file.txt",
title: "My attached file",
url: "http://example.com/file.txt",
filename: "file.txt",
content_type: "text/plain",
file_size: 1024,
}
]
}
will output an attachment block
```html
```
Attachment Links
Attachments can be be rendered inline as links
Some information about [AttachmentLink:file.pdf]
with options provided
{
attachments: [
{
id: "file.pdf",
title: "My PDF",
url: "http://example.com/file.pdf",
filename: "file.pdf",
content_type: "application/pdf",
file_size: 32768,
number_of_pages: 2,
}
]
}
will output an attachment link within a paragraph of text
```html
Some information about
```
Inline Attachments (DEPRECATED: use AttachmentLink:attachment-id instead)
Attachments can be linked to inline
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: "http://example.com/my-thorough-study.pdf",
}
]
}
will output an attachment within a block of text
```html
Details referenced in
```
Image Attachments (DEPRECATED: use Image:image-id instead)
Attachments can be used to embed an image within the document
[embed:attachments:image:45ee0eea-bc53-4f14-81eb-9e75d33c4d5e]
with options provided
{
attachments: [
{
content_id: "45ee0eea-bc53-4f14-81eb-9e75d33c4d5e",
title: "A lovely landscape",
url: "http://example.com/lovely-landscape.jpg",
}
]
}
will output a image section
```html
```
Images
Images can be embedded as a figure with optional caption.
[Image:filename.png]
with options provided
{
images: [
{
alt_text: "Some alt text",
caption: "An optional caption",
credit: "An optional credit",
url: "http://example.com/lovely-landscape.jpg",
id: "filename.png",
}
]
}
will output a image section
```html
An optional caption
Image credit: An optional credit
```
Link
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: "http://example.com",
title: "An excellent website",
}
]
}
will output
```html
A link to An excellent website
```
Contact
[Contact:df62690f-34a0-4840-a7fa-4ef5acc18666]
with options provided
{
contacts: [
{
id: 123,
content_id: "df62690f-34a0-4840-a7fa-4ef5acc18666",
title: "Government Digital Service",
email: "[email protected]",
contact_numbers: [
{ label: "helpdesk", number: "+4412345 67890"}
]
}
]
}
will output
```html
Government Digital Service
Email [email protected]
helpdesk +4412345 67890
```
Button
An accessible way to add button links into content, that can also allow cross domain tracking with Google Analytics
This button component uses the component from the components gem for use in govspeak.
You must use the link syntax within the button tags.
Examples
To get the most basic button.
{button}[Continue](https://gov.uk/random){/button}
which outputs
html
<a role="button" class="gem-c-button govuk-button" href="https://gov.uk/random">
Continue
</a>
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}
which outputs
```html Start Now
</a> ```
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](https://example.com/external-service/start-now)
{/button}
which outputs
```html Start Now
</a> ```