alphagov · domoscargin · Nov 29, 2022 · Nov 2, 2022 · Nov 2, 2022 · Nov 2, 2022
diff --git a/lib/file-helper.js b/lib/file-helper.js
@@ -37,10 +37,16 @@ exports.getNunjucksCode = path => {
   // Omit any `{% extends "foo.njk" %}` nunjucks code, because we extend
   // templates that only exist within the Design System – it's not useful to
   // include this in the code we expect others to copy.
-  let content = parsedFile.content.replace(
-    /{%\s*extends\s*\S*\s*%}\s+/,
-    ''
-  )
+  let content = parsedFile.content
+    .replace(
+      /{%\s*extends\s*\S*\s*%}\s+/,
+      ''
+    )
+    // Remove empty lines to avoid broken markdown rendering
+    .replace(
+      /^\s*[\r\n]/gm,
+      ''
+    )
 
   return content
 }
@@ -107,12 +113,15 @@ exports.getHTMLCode = path => {
 
   return beautify(html.trim(), {
     indent_size: 2,
-    end_with_newline: true,
-    // If there are multiple blank lines, reduce down to one blank new line.
-    max_preserve_newlines: 1,
+    end_with_newline: false,
+    // Remove blank lines
+    max_preserve_newlines: 0,
     // set unformatted to a small group of elements, not all inline (the default)
     // otherwise tags like label arent indented properly
-    unformatted: ['code', 'pre', 'em', 'strong']
+    unformatted: ['code', 'pre', 'em', 'strong'],
+    // Ensure no empty lines after <head> and <body> tags - this breaks markdown
+    // rendering
+    extra_liners: []
   })
 }
 

diff --git a/lib/metalsmith.js b/lib/metalsmith.js
@@ -232,8 +232,8 @@ module.exports = metalsmith(__dirname) // __dirname defined by node.js: name of
       },
 
       // Markdown engine options
+      mangle: false, // Don't mangle emails
       smartypants: true, // use "smart" typographic punctuation
-      pedantic: true,
       highlight: highlighter
     }
   }))

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -54,7 +54,7 @@
     "jest-environment-jsdom": "^29.3.1",
     "jest-puppeteer": "^6.1.1",
     "js-beautify": "^1.14.7",
-    "jstransformer-marked": "~1.0.3",
+    "jstransformer-marked": "1.2.0",
     "jstransformer-nunjucks": "^1.1.0",
     "marked": "^4.2.2",
     "metalsmith": "^2.5.1",

diff --git a/src/accessibility.md.njk b/src/accessibility.md.njk
@@ -14,7 +14,7 @@ This page explains how the team works to ensure the Design System and Frontend a
 
 ## Accessibility statement for the GOV.UK Design System website
 
-This accessibility statement applies to the GOV.UK Design System at https://design-system.service.gov.uk/, and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System.
+This accessibility statement applies to the GOV.UK Design System at <https://design-system.service.gov.uk/>, and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System.
 
 The GOV.UK Design System team wants as many people as possible to be able to use this website. For example, that means you should be able to:
 
@@ -30,7 +30,7 @@ The team has also made the website text as simple as possible to understand.
 
 ### Feedback and contact information
 
-The GOV.UK Design System team is always looking to improve the accessibility of this website. If you find any problems that are not listed on this page or think this website is not meeting accessibility requirements, email the GOV.UK Design System team at govuk-design-system-support@digital.cabinet-office.gov.uk
+The GOV.UK Design System team is always looking to improve the accessibility of this website. If you find any problems that are not listed on this page or think this website is not meeting accessibility requirements, email the GOV.UK Design System team at <govuk-design-system-support@digital.cabinet-office.gov.uk>
 
 The GOV.UK Design System team will review your request and get back to you in 2 working days.
 
@@ -103,4 +103,4 @@ If you're using these products, you should start [updating your service to use t
 If you have any questions or need help, contact the GOV.UK Design System team:
 
 - using the [#govuk-design-system channel on cross-government Slack](https://ukgovernmentdigital.slack.com/app_redirect?channel=govuk-design-system)
-- by email at govuk-design-system-support@digital.cabinet-office.gov.uk
+- by email at <govuk-design-system-support@digital.cabinet-office.gov.uk>
diff --git a/src/community/contribution-criteria/index.md.njk b/src/community/contribution-criteria/index.md.njk
@@ -79,7 +79,6 @@ Before a new component or pattern is published the working group reviews the imp
       },
       {
         html: "<p>It has been tested  in user research and shown to work with a representative sample of users, including those with disabilities.</p>
-
         <p class='govuk-!-margin-bottom-0'>Components and patterns which are not proven usable can be published as experimental. But they must be clearly based on relevant user research from other organisations and best practice, and meet the other criteria.</p>"
       }
     ],
@@ -89,9 +88,7 @@ Before a new component or pattern is published the working group reviews the imp
       },
       {
         html: "<p>It reuses existing styles and components in the Design System where relevant.</p>
-
         <p>Both the guidance and any content included in examples must follow the <a href='https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style'>GOV.UK content style guide</a>.</p>
-
         <p class='govuk-!-margin-bottom-0'>If there is code, it follows the <a href='https://github.com/alphagov/govuk-frontend/blob/main/CONTRIBUTING.md#conventions-to-follow'>GOV.UK Frontend coding standards</a> and is ready to merge in GOV.UK Frontend.</p>"
       }
     ],
@@ -101,9 +98,7 @@ Before a new component or pattern is published the working group reviews the imp
       },
       {
         html: "<p>The implementation is versatile enough that the component or pattern can be used in a range of different services that may need it.</p>
-
         <p>For example, a versatile date input component could be set up to ask for a year only, a month and year only, a precise date, or any other combination you may need.</p>
-
         <p class='govuk-!-margin-bottom-0'>The component or pattern must also have been tested and shown to work with a range of <a href='https://www.gov.uk/service-manual/technology/designing-for-different-browsers-and-devices'>browsers, assistive technologies and devices</a>.</p>"
       }
     ]

diff --git a/src/community/develop-a-component-or-pattern/index.md.njk b/src/community/develop-a-component-or-pattern/index.md.njk
@@ -9,7 +9,7 @@ order: 4
 
 The Design System team focuses on developing [prioritised components and patterns](/community/upcoming-components-patterns/) with the community. However, anyone can choose to work on something from the [list of discussions on GitHub](https://github.com/orgs/alphagov/projects/43/views/2). 
 
-If you see something you'd like to work on, join the discussion in the contribution's issue page or email the Design System team at govuk-design-system-support@digital.cabinet-office.gov.uk.
+If you see something you'd like to work on, join the discussion in the contribution's issue page or email the Design System team at <govuk-design-system-support@digital.cabinet-office.gov.uk>.
 
 If you have an idea for a new component or pattern that’s not already on the list, [propose it](/community/propose-a-component-or-pattern/).
 

diff --git a/src/community/propose-a-content-change-using-github/index.md.njk b/src/community/propose-a-content-change-using-github/index.md.njk
@@ -21,7 +21,7 @@ If you do not have one already, you can [create a GitHub account for free](https
 If you get stuck whilst following these steps and you need help, you can:
 
 - get in touch on [#govuk-design-system channel on cross-government Slack](https://ukgovernmentdigital.slack.com/app_redirect?channel=govuk-design-system)
-- email the GOV.UK Design System team on <br>govuk-design-system-support@digital.cabinet-office.gov.uk
+- email the GOV.UK Design System team on <br><govuk-design-system-support@digital.cabinet-office.gov.uk>
 
 ## 1. Go to the page you want to edit
 

diff --git a/src/community/roadmap/index.md.njk b/src/community/roadmap/index.md.njk
@@ -29,6 +29,7 @@ We recently:
 ## Working on now
 
 We're working to:
+
 - host community co-design work to [turn task-list into a component](/patterns/task-list-pages/)
 - host community co-design work to make maps better
 - release the [Hide this page](https://github.com/alphagov/govuk-design-system-backlog/issues/213) component
@@ -38,6 +39,7 @@ We're working to:
 ## Coming up next
 
 We're getting ready to:
+
 - implement our [proposal](https://github.com/alphagov/govuk-frontend/discussions/2607) for reducing browser support
 - release the [Summary Card](https://github.com/alphagov/govuk-design-system-backlog/issues/210) variant
 - make it easier to find information about contributing and the community
@@ -47,6 +49,7 @@ We're getting ready to:
 ## Future plans
 
 We plan to:
+
 - investigate Sass module system
 - make sure the Design System meets WCAG 2.2
 - investigate removing compatibility mode
diff --git a/src/components/accordion/index.md.njk b/src/components/accordion/index.md.njk
@@ -55,6 +55,7 @@ Do not use the accordion component if the amount of content inside will make the
 Accordions, [tabs](/components/tabs/) and [details](/components/details/) all work by hiding sections of content which a user can choose to reveal. Avoid using any of these components within one another.
 
 If you decide to use one of these components, consider if:
+
 - the user needs to look at more than one section at a time — an accordion can show multiple sections at a time, unlike tabs
 - the user needs to switch quickly between sections — tabs can show content without pushing other sections down the page, unlike accordions
 - there are many sections of content — accordions can fit more sections as they’re arranged vertically, unlike tabs which are arranged horizontally
@@ -71,6 +72,7 @@ The accordion component uses JavaScript. When JavaScript is not available, users
 An accordion will usually start with all sections hidden. To show a section, the user can interact anywhere in the heading button.
 
 The heading button includes all of these areas:
+
 - heading text
 - summary line (if you decide to add one)
 - call-to-action text to 'show' or 'hide'

diff --git a/src/components/cookie-banner/index.md.njk b/src/components/cookie-banner/index.md.njk
@@ -20,10 +20,12 @@ Allow users to accept or reject cookies which are not essential to making your s
 Use this component if your service sets any cookies on a user’s device.
 
 Remember, you must:
+
 - tell users about the cookies your service sets on their device
 - let users accept or reject any cookies that are not essential to providing your service
 
 The term ‘non-essential cookies’ includes:
+
 - HTML5 local storage
 - service workers
 - any other technologies that store files on the user’s device
@@ -37,6 +39,7 @@ This component page shows several options for using a cookie banner, based on th
 [Audit and categorise your cookies](/patterns/cookies-page/#auditing-and-categorising-your-cookies) as shown in the cookies page pattern to help you choose the best option for your service.
 
 You must not take the information on this page as legal advice. Your organisation is responsible and accountable for what they do to comply with data protection legislation, such as:
+
 - Privacy and Electronic Communications Regulations (PECR)
 - General Data Protection Regulation (GDPR)
 
@@ -45,15 +48,18 @@ Check with your organisation's privacy expert to see how data protection legisla
 ## How it works
 
 Show the cookie banner every time the user accesses your service until they either:
+
 - accept or reject cookies using the buttons in the cookie banner
 - save their cookie preferences on the service’s [cookies page](/patterns/cookies-page/)
 
 Once the user has accepted or rejected cookies, the cookie banner should:
+
 - hide the cookie banner message
 - show a confirmation message — and a 'hide' button to let the user close the banner
 - set a cookie to save the user’s preferences for 1 year
 
 Make sure the cookie banner does not:
+
 - show when the user visits again, once their preferences have been saved
 - set any non-essential cookies unless the user accepted them on a previous visit
 
@@ -114,6 +120,7 @@ When the page loads, the `hidden` html attribute hides the component, as well as
 Use JavaScript to show cookie banner messages to users that have not accepted or rejected cookies by removing the `hidden` attribute as needed.
 
 Write your own JavaScript code so that when the user accepts or rejects cookies, the cookie banner will:
+
 - hide the cookie message by adding the hidden attribute
 - show a confirmation message by removing its hidden attribute
 - give the confirmation message the `tabindex="-1"` and `role="alert"` attributes — this will allow the element to be focused so assistive technology can read the message
@@ -155,6 +162,7 @@ You can use this example text for a service which sets essential and analytics c
 ### If you’re using more than one type of non-essential cookie
 
 You can use this example text for a service that set:
+
 - essential cookies
 - analytics cookies
 - functional cookies to remember the user’s settings but are not essential
@@ -173,6 +181,7 @@ When the user accepts or rejects cookies, a confirmation message will display. F
 However, a visible focus indicator does not display around the confirmation message. This is different from the notification banner, which does display a visible focus indicator.
 
 We decided to remove the visible focus indicator from the confirmation message for a few reasons, as:
+
 - a user cannot interact with it
 - it's the first element, at the very top of the page
 - it displays in place of the cookie message, which is the last thing the user interacted with

diff --git a/src/components/footer/index.md.njk b/src/components/footer/index.md.njk
@@ -36,8 +36,8 @@ Make it clear whether content is available for re-use - and if it is, under what
 ## Adding links
 
 You can add links to:
-- [privacy notice](https://www.gov.uk/service-manual/design/collecting-personal-information-from-users
-)
+
+- [privacy notice](https://www.gov.uk/service-manual/design/collecting-personal-information-from-users)
 - [accessibility statement](https://www.gov.uk/service-manual/helping-people-to-use-your-service/publishing-information-about-your-services-accessibility)
 - [cookies page](/patterns/cookies-page/)
 - terms and conditions

diff --git a/src/components/notification-banner/index.md.njk b/src/components/notification-banner/index.md.njk
@@ -93,5 +93,6 @@ To make the green version of the notification banner accessible:
 ## Research on this component
 
 We need more research to understand:
+
 - how common it is for users to miss important information in notification banners (including users of assistive technology, who might skip straight to the `h1`)
 - whether it’s sometimes helpful to allow users to dismiss notifications, and how to do this
diff --git a/src/components/pagination/index.md.njk b/src/components/pagination/index.md.njk
@@ -16,6 +16,7 @@ Help users navigate forwards and backwards through a series of pages. For exampl
 ## When to use this component
 
 Consider using pagination when:
+
 - showing all the content on a single page makes the page take too long to load
 - most users will only need the content on the first page or first few pages
 

diff --git a/src/components/radios/index.md.njk b/src/components/radios/index.md.njk
@@ -63,6 +63,7 @@ If you're asking more than one question on the page, do not set the contents of
 In some cases, you can choose to display radios 'inline' beside one another (horizontally).
 
 Only use inline radios when:
+
 - the question only has two options
 - both options are short
 

diff --git a/src/components/tabs/index.md.njk b/src/components/tabs/index.md.njk
@@ -48,6 +48,7 @@ Test your content without tabs first. Consider if it’s better to:
 Tabs, [accordions](/components/accordion/), and [details](/components/details/) all hide sections of content which a user can choose to reveal.
 
 If you decide to use one of these components, consider if:
+
 - the user does not need to view more than one section at a time — consider using tabs
 - the user needs to switch quickly between sections — tabs can show content without pushing other sections down the page, unlike accordions
 - there are many pieces of content — tabs can fit fewer sections as they’re arranged horizontally, unlike accordions which are arranged vertically

diff --git a/src/get-started/extending-and-modifying-components/index.md.njk b/src/get-started/extending-and-modifying-components/index.md.njk
@@ -13,6 +13,7 @@ You might need to extend or modify components in the GOV.UK Design System from t
 - meet a specific user need in your service
 
 Consider whether your changes:
+
 - help the long term maintenance of your service
 - allow you to safely install updates from the GOV.UK Design System
 - reduce the risk of technical debt