Doesn't work with standard structural HTML eg. Markdown output

[steadysupply]

The following Markdown

# Pithy title

Rambling paragraph

> Quote from Shakespeare

## Shopping list

 - Eggs
 - Bacon
 - Facemask

produces the following structured, accessible HTML markup

<h1>Pithy title</h1>
<p>Rambling paragraph</p>
<blockquote>
<p>Quote from Shakespeare</p>
</blockquote>
<h2>Shopping list</h2>
<ul>
<li>Eggs</li>
<li>Bacon</li>
<li>Facemask</li>
</ul>

.

None of the bog-standard HTML elements generated above have CSS rules in the stylesheets offered here.

It appears there might be a mapping from the structural HTML elements to CSS classes used here (for example HTML's h1 could map to govuk-heading-xl in src/govuk/core/_typography.scss here).

• Does such a mapping exist? If so, where can I find it?
• Am I looking at the wrong project, ie. are there stylesheets offered elsewhere for standard structured HTML?

[steadysupply]

I rendered the above Markdown with the govspeak Ruby package which produces the following HTML

<h1 id="pithy-title">Pithy title</h1>

<p>Rambling paragraph</p>

<blockquote>
  <p class="last-child">Quote from Shakespeare</p>
</blockquote>

<h2 id="shopping-list">Shopping list</h2>

<ul>
  <li>Eggs</li>
  <li>Bacon</li>
  <li>Facemask</li>
</ul>

Whilst some HTML attributes have been added, no classes with rules here are added.

[andymantell]

The design system repository has some code you could use to do this. See https://github.com/alphagov/govuk-design-system/blob/master/src/stylesheets/main.scss#L274 where you should find this:

.app-prose-scope {
  h1 {
    @extend %govuk-heading-xl;
  }

  h2 {
    @extend %govuk-heading-l;
  }

  h3 {
    @extend %govuk-heading-m;
  }

  ...snip...

If you then put this app-prose-scope class on any sections that are coming from markdown they will appear fully styled.

I believe the decision to not style top level elements was probably done to reduce the likelihood of conflicting with anything else that may be on the page. But by introducing it in a confined area you should be safe enough.

See also -> #778

[steadysupply]

Thanks @andymantell, it appears that the mapping I asked about is at least partially defined there. The relationship between this repo and the govuk-design-system repo is not immediately clear to me; does this repo use code from there or vice versa?

[andymantell]

The govuk-design-system repository is the code for the https://design-system.service.gov.uk/ website - it's the documentation effectively. The govuk-frontend repository is the main one which contains the code that is intended to be reused by services. The design system consumes the code from govuk-frontend.

The design system repo contains additional code which is just for the purposes of that website alone - for example you won't find styles for the grey navigation bar or the sub navigation in this repository. The above snippet for introducing prose scope is fairly safe but if you want to stick 100% with the stuff that's in govuk-frontend you could see if your markdown library allows you to extend it to output the classes. For example, I created this custom markdown renderer for use at HM Land Registry:

https://github.com/LandRegistry/dps-verification-ui/blob/master/verification_ui/custom_extensions/jinja_markdown_filter/gov_renderer.py

You might find you can do something similar for whatever markdown library you are using.

[steadysupply]

Thanks for clarifying, very helpful.

As a side note, the README for govuk-design-system doesn't actually describe what the repo is for -- perhaps your first paragraph could be inserted at the head of that repo's README to avoid future confusion.

custom markdown renderer

Thanks for linking to your extension, I might refer to it if needed. However, that's exactly the type of thing I was trying to avoid doing in posting my question here!

The workflow I envisioned was

• Author some Markdown
• Pass file to cmark to get structured HTML
• Serve HTML with a GDS-provided stylesheet
• My document will be structured, accessible and pleasant on the eye

It looks like I can't get a release of usable CSS (ie. not Sass) that fits into my workflow above.

Closing this issue.

[andymantell]

To clarify - I am not from GDS, I was just in the vicinity and thought I would help.

If you think the readme needs improvement it might be worth leaving this ticket open, or opening one specifically to get the readme improved.

[steadysupply]

in the vicinity and thought I would help

Yep, I got that. Much appreciated :)

ticket

alphagov/govuk-design-system#1287