feat: define global urls with markdown refs

data/markdown_refs.yaml

@@ -0,0 +1,11 @@
+govuk: https://www.gov.uk/
+govuk_frontend_design_system: https://frontend.design-system.service.gov.uk/
+govuk_design_system: https://design-system.service.gov.uk/
+govuk_prototype_kit: https://prototype-kit.service.gov.uk
+govuk_design_system_accessibility: https://design-system.service.gov.uk/accessibility/
+
+component_radio: /components/radios/
+component_checkbox: /components/checkbox/
+pattern_check_answers: /patterns/check-answers/
+
+lib_nunjucks: https://mozilla.github.io/nunjucks/

lib/metalsmith.js

@@ -75,7 +75,13 @@ module.exports = metalsmith
   .metadata({
     title: '[TITLE NOT SET]',
     colours,
-
+    // add a list of .md links and/ or image references that can be reused across all pages
+    // using the [title][identifier] notation
+    globalLinks: (function() {
+      const source = metalsmith.matter.parse(metalsmith.matter.wrap(readFileSync(join(process.cwd(), 'data', 'markdown_refs.yaml'), 'utf-8')))
+      delete source.contents
+      return source
+    }()),
     // include access to metalsmith environment variables
     // used to e.g. detect when we're building in a preview environment
     env: (value) => metalsmith.env(value)
@@ -187,6 +193,7 @@ module.exports = metalsmith
   // render markdown in source files
   .use(
     markdown({
+      globalRefs: 'globalLinks',
       render(source) {
         return marked.parse(source)
       }

src/accessibility-statement.md

@@ -6,7 +6,7 @@ layout: layout-single-page-prose.njk
 
 # Accessibility statement
 
-The GOV.UK Design System team (the team) is committed to making its website at [design-system.service.gov.uk](https://design-system.service.gov.uk/) and the GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk](https://frontend.design-system.service.gov.uk/) accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018.
+The GOV.UK Design System team (the team) is committed to making its website at [design-system.service.gov.uk][govuk_frontend_design_system] and the GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk][govuk_frontend_design_system_] accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018.
 
 This accessibility statement applies to both websites and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System.
 
@@ -23,9 +23,9 @@ AbilityNet has [advice on making your device easier to use](https://mcmw.ability
 
 ## Compliance status
 
-The Design System website at [design-system.service.gov.uk](https://design-system.service.gov.uk/) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard.
+The Design System website at [design-system.service.gov.uk][govuk_design_system] is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard.
 
-The GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk](https://frontend.design-system.service.gov.uk/) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard.
+The GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk][govuk_frontend_design_system] is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard.
 
 The GOV.UK Frontend codebase at [github.com/alphagov/govuk-frontend](https://github.com/alphagov/govuk-frontend) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.2 AA standard.
 
@@ -82,11 +82,11 @@ Additional accessibility concerns from the GOV.UK Frontend codebase include:
 
 This statement was prepared on 23 October 2019. It was last reviewed and updated on 2 August 2023.
 
-The [GOV.UK Design System website](https://design-system.service.gov.uk/) was last audited for accessibility issues by an external group on 7 October 2019. The test was carried out by the [Digital Accessibility Centre (DAC)](https://digitalaccessibilitycentre.org/).
+The [GOV.UK Design System website][govuk_design_system] was last audited for accessibility issues by an external group on 7 October 2019. The test was carried out by the [Digital Accessibility Centre (DAC)](https://digitalaccessibilitycentre.org/).
 
 DAC tested a sample of pages to cover the different content types in the GOV.UK Design System website. They were:
 
-- [the homepage](https://design-system.service.gov.uk/)
+- [the homepage][govuk_design_system]
 - [a short content page](https://design-system.service.gov.uk/community/design-system-working-group/)
 - [a long content page](https://design-system.service.gov.uk/styles/layout/)
 - [an overview page](https://design-system.service.gov.uk/community/)

src/accessibility/accessibility-strategy/index.md

@@ -65,9 +65,9 @@ An ‘accessibility concern’ is our umbrella term for any question about the a
 Accessibility concerns can surface in any product, including:
 
 - [GOV.UK Frontend](https://design-system.service.gov.uk/get-started/production/)
-- the [GOV.UK Design System website](https://design-system.service.gov.uk/)
-- the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/)
-- the [GOV.UK Frontend technical documentation website](https://frontend.design-system.service.gov.uk/)
+- the [GOV.UK Design System website][govuk_design_system]
+- the [GOV.UK Prototype Kit][govuk_prototype_kit]
+- the [GOV.UK Frontend technical documentation website][govuk_frontend_design_system]
 - other content produced by the GOV.UK Design System team
 
 The GOV.UK Design System’s top focus for accessibility is on styles and components included in GOV.UK Frontend and patterns built using GOV.UK Frontend.
@@ -287,13 +287,13 @@ If an incoming query is more than a quickly-answered question, it will be record
 
 By keeping accessibility concerns in the same place as all our GitHub issues, the team can more easily identify accessibility concerns related to other items. Addressing and storing accessibility concerns separate from GitHub issues could lead to them receiving less attention.
 
-If an accessibility concern turns out to be a bug the team cannot quickly fix, the team will determine whether it should be recorded in the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/).
+If an accessibility concern turns out to be a bug the team cannot quickly fix, the team will determine whether it should be recorded in the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility].
 
 We also will record relevant accessibility concerns for specific styles, components or patterns in their corresponding guidance pages.
 
 ### Recording WCAG compliance status
 
-If the GOV.UK Design System does not meet the requirements of level AA accessibility compliance, the team will update the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/) and keep the records of changes required until compliance is met.
+If the GOV.UK Design System does not meet the requirements of level AA accessibility compliance, the team will update the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility] and keep the records of changes required until compliance is met.
 
 ## Proposed accessibility activities
 
@@ -343,7 +343,7 @@ Initially, the team will assess the performance of this accessibility strategy b
 - use of the strategy to guide and improve the GOV.UK Design System team’s decision-making
 - progress and completion of activities mentioned in the strategy
 - number of accessibility concerns recorded as GitHub issues in the team’s repositories
-- number of accessibility concerns listed in the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/)
+- number of accessibility concerns listed in the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility]
 
 #### Additional indicators
 
@@ -359,7 +359,7 @@ If capacity is available to expand measurement efforts, additional performance i
 
 ### Recording performance measurement results
 
-The team will gather performance measurement results every 6 months and record them in the team’s internal documentation. The team will also review the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/) every 6 months and update as needed.
+The team will gather performance measurement results every 6 months and record them in the team’s internal documentation. The team will also review the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility] every 6 months and update as needed.
 
 The team will use the results of performance measurement and accessibility statement reviews to help inform quarterly planning.
 

src/components/back-link/index.md

@@ -74,7 +74,7 @@ Make sure the link takes users to the previous page they were on, in the state t
 
 Where possible, ensure the back link works even when JavaScript is not available. If this is not possible, you should hide the back link when JavaScript is not available.
 
-There are 2 ways to use the back link component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the back link component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "back-link", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }}
 

src/components/breadcrumbs/index.md

@@ -60,7 +60,7 @@ The breadcrumbs should start with your 'home' page and end with the parent secti
   <p>Make sure no other interactive elements are too close to the breadcrumbs. This is to make sure users can easily interact with the breadcrumbs. This relates to WCAG 2.2 success criterion <a href="https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html">2.5.8 Target Size (minimum)</a>.</p>
 </div>
 
-There are 2 ways to use the breadcrumbs component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the breadcrumbs component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "breadcrumbs", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }}
 

src/components/button/index.md

@@ -49,8 +49,8 @@ Write button text in sentence case, describing the action it performs. For examp
 - ‘Save and come back later’ when a user can save their information and come back later
 - ‘Add another’ to add another item to a list or group
 - ‘Pay’ to make a payment
-- ‘Confirm and send’ on a [check answers](/patterns/check-answers/) page that does not have any legal content a user must agree to
-- ‘Accept and send’ on a [check answers](/patterns/check-answers/) page that has legal content a user must agree to
+- ‘Confirm and send’ on a [check answers][pattern_check_answers] page that does not have any legal content a user must agree to
+- ‘Accept and send’ on a [check answers][pattern_check_answers] page that has legal content a user must agree to
 - ‘Sign out’ when a user is signed in to an account
 
 You may need to include more or different words to better describe the action. For example, ‘Add another address’ and ‘Accept and claim a tax refund’.
@@ -65,7 +65,7 @@ Align the primary action button to the left edge of your form.
   <p>Do not decrease the height or target area of buttons. This is to make sure users can easily interact with buttons. This is to comply with WCAG 2.2 success criterion <a href="https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html">2.5.8 Target Size (minimum)</a>.</p>
 </div>
 
-There are 2 ways to use the button component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the button component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 ### Default buttons
 

src/components/checkboxes/index.md

@@ -22,7 +22,7 @@ Use the checkboxes component when you need to help users:
 
 ## When not to use this component
 
-Do not use the checkboxes component if users can only choose one option from a selection. In this case, use the [radios component](/components/radios/).
+Do not use the checkboxes component if users can only choose one option from a selection. In this case, use the [radios component][component_radio].
 
 ## How it works
 
@@ -49,7 +49,7 @@ If you're asking just [one question per page](/patterns/question-pages/#start-by
 
 Read more about [why and how to set legends as headings](/get-started/labels-legends-headings/).
 
-There are 2 ways to use the checkboxes component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the checkboxes component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "checkboxes", example: "default", html: true, nunjucks: true, open: false, size: "m", titleSuffix: "second" }) }}
 

src/components/date-input/index.md

@@ -37,7 +37,7 @@ Make sure that any example dates you use in hint text are valid for the question
 
 Accept month names written out in full or abbreviated form (for example, ‘january’ or ‘jan’) as some users may enter months in this way.
 
-There are 2 ways to use the date input component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the date input component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "date-input", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }}
 

src/components/details/index.md

@@ -33,7 +33,7 @@ The details component is less visually prominent than tabs and accordions, so te
 
 The details component is a short link that shows more detailed help text when a user clicks on it.
 
-There are 2 ways to use the details component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the details component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "details", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }}
 

src/components/error-message/index.md

@@ -11,7 +11,7 @@ layout: layout-pane.njk
 {% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
 {% from "govuk/components/tag/macro.njk" import govukTag %}
 
-This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/).
+This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk].
 
 {% set wcagCallout %}
 
@@ -181,7 +181,7 @@ Use template messages for common errors on:
 - [file upload](/components/file-upload/#error-messages)
 - [names](/patterns/names/#error-messages)
 - [National Insurance numbers](/patterns/national-insurance-numbers/#error-messages)
-- [radios](/components/radios/#error-messages)
+- [radios][component_radio]
 - [telephone numbers](/patterns/telephone-numbers/#error-messages)
 - [text input](/components/text-input/#error-messages)
 - [textarea](/components/textarea/#error-messages)

src/components/error-summary/index.md

@@ -32,7 +32,7 @@ As well as showing an error summary, follow the [validation pattern](/patterns/v
 
 And make your [error messages](/components/error-message/#be-clear-and-concise) clear and concise.
 
-There are 2 ways to use the error summary component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the error summary component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "error-summary", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }}
 

src/components/fieldset/index.md

@@ -17,7 +17,7 @@ Use the fieldset component when you need to show a relationship between multiple
 
 {{ example({ group: "components", item: "fieldset", example: "address-group", html: true, nunjucks: true, open: false, size: "xl", loading: "eager" }) }}
 
-If you’re using the examples or macros for [radios](/components/radios/), [checkboxes](/components/checkboxes/) or [date input](/components/date-input/), the fieldset will already be included.
+If you’re using the examples or macros for [radios][component_radio], [checkboxes][component_checkbox] or [date input](/components/date-input/), the fieldset will already be included.
 
 ## How it works
 

src/components/file-upload/index.md

@@ -11,7 +11,7 @@ layout: layout-pane.njk
 {% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
 {% from "govuk/components/tag/macro.njk" import govukTag %}
 
-This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/).
+This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk].
 
 {% set wcagCallout %}
 
@@ -69,7 +69,7 @@ To upload a file, the user can either:
   <p>You can make it easier for the user to reuse a file by showing it as an option for the user to select instead of the file upload. Consider users on public devices before choosing to make the file available to preview or download. This is to comply with WCAG 2.2 success criterion <a href="https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html">3.3.7 Redundant Entry</a>.</p>
 </div>
 
-There are 2 ways to use the file upload component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro.
+There are 2 ways to use the file upload component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro.
 
 {{ example({ group: "components", item: "file-upload", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }}