Generate and implement heading captions

[domoscargin]

Done when

• [x] Captions are decided
• [ ] Captions are technically implemented

Captions will be added to this spreadsheet: https://docs.google.com/spreadsheets/d/1Y-c8e_syvu2hT8jLr0yNKigNAGpf1yU7WJlal3iLSIs/edit#gid=573269404

Detail

On some documentation pages, we have a caption frontmatter property. This defines the h1's caption content.

There are two easy ways that I can see to generate this caption (and one slightly more involved way):

1. hardcode the span in the markdown like such:

<span class="govuk-caption-xl">govuk-caption-xl</span>

This creates a problem: marked wraps <span> elements in a paragraph. So we could either add an empty wrapping <div>, or use a custom renderer for <p> elements in marked.

2. Insert the caption into the HTML string.

Once we have our generated HTML string, we could find the <h1> and insert the caption before it. I don't think there should be any case where we need to caption an <h2> or higher, and the <h1> should be quite early in the HTML string, so hopefully it wouldn't be a particularly large performance hit.

3. A custom marked extension for <span> elements https://marked.js.org/using_pro#extensions

We could potentially do some extra logic here to cover the captions.

Other issues to consider

We may potentially have to define the heading/caption size in the frontmatter if we want to use different sizes on different pages.