Go back

Markdown

This guide shows you some playbook specific tips. For general guidance on Markdown consult these references:

Abbreviations

We use markdown-it-abbr to render abbreviations.

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium
The HTML specification is maintained by the W3C.

renders as:

The HTML specification is maintained by the W3C.

Admonition

We use markdown-it-admonition to render callouts. We currently only support styling for warning to align with the NHS warning callout component

!!! warning Warning title
warning detail text
!!!

renders as:

Warning title

warning detail text

Cards

We use markdown-it-container to wrap sections of content in additional HTML. This is used to format content as the NHS Card design component.

Wrap the markdown content with ::: card and ::: markers

This is particularly effective when combined with definition lists.

::: card
### Section heading

Term 1
: Definition one

Term 2
: Definition two
:::

render as:

Section heading

Term 1
Definition one
Term 2
Definition two

Code tabs

We use markdown-it-codetabs to provide code snippets in multiple languages.

    ```java [g1:Java]
    logger.info("Here is some data - {}", data);
    ```

    ```javascript [g1:Javascript]
    logger.log('info', 'Here is some data -  %s', data);
    ```

renders as:

logger.info("Here is some data - {}", data);
logger.log('info', 'Here is some data -  %s', data);

Definition list

We use markdown-it-deflist to provide definition lists, styled to match the NHS Summary list component.

Term 1
: Definition one including `nested markdown`
  and multi line content

Term 2
: Definition two

renders as:

Term 1
Definition one including nested markdown
and multi line content
Term 2
Definition two

Expanding details

We use markdown-it-container to provide an expanding details component.

Wrap the markdown content with ::: details and ::: markers

::: details show more
 
Content here

:::

renders as:

show more

Content here

Highlight

We use markdown-it-mark to provided highlight of text.

==highlighted==

renders as:

highlighted

Supertext and subtext

We use markdown-it-sub and markdown-it-sup to provide super-text and sub-text

H~2~0
29^th^

renders as:

H20
29th

Tables

We use a MultiMarkdown table syntax to enhance rendering of tables.

This provides:

  • Cell spans over columns
  • Cell spans over rows
  • Divide rows into sections
  • Multiple table headers
  • Table caption
  • Block-level elements such as lists, codes…
  • Omitted table header

Emojis

We use the markdown-it-emoji extension to render github supported emojis.

Here are some useful examples:

  • ✅ :white_check_mark:
  • ❌ :x:
  • ❓ :question:
  • 👍 :+1:
  • 💯 :100:
  • 🔧 :wrench:
  • 🌱 :seedling:
  • 📝 :memo:
  • ⚠️ :warning:
  • ⛔ :no_entry:

A complete list can be found here

Improve the playbook

If you spot anything factually incorrect with this page or have ideas for improvement, please share your suggestions.

Before you start, you will need a GitHub account. Github is an open forum where we collect feedback.

Suggest a change to this page

Published: