lfdebrux
commented
2 years ago Chatted to @domoscargin about this to get more context, as it's not immediately clear where the captions come from.
The captions were added in PR alphagov/govuk-prototype-kit#1186, as part of the content review of the prototype kit pages. The idea of the caption was that it would be the same as the sections on the docs index page, to help the user see where they are in the documentation; for instance, all the pages in the make-first-prototype folder have the same caption, 'Build a basic prototype', except for start.md, which has the title 'Build a basic prototype', and starts the journey.
We might decide that actually this feature isn't needed, and close this PR, but at least now what we might be missing out on 😁
trang-erskine
Izabela-16
NoraGDS
Done when
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
captionfrontmatter 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):
<span class="govuk-caption-xl">govuk-caption-xl</span>This creates a problem:
markedwraps<span>elements in a paragraph. So we could either add an empty wrapping<div>, or use a custom renderer for<p>elements inmarked.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.markedextension for<span>elements https://marked.js.org/using_pro#extensionsWe 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.