fix broken anchor links and add instructions

UKHomeOffice · Nov 20, 2023 · 233d7e3 · 233d7e3
1 parent c5647cd
commit 233d7e3
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 3 deletions.
diff --git a/docs/standards/managing-security-software-dependencies.md b/docs/standards/managing-security-software-dependencies.md
@@ -35,7 +35,7 @@ Home Office engineering teams are required to manage software dependencies proac
 - [You MUST assess the security of external components before introducing them into software designs](#you-must-assess-the-security-of-external-components-before-introducing-them-into-software-designs)
 - [You MUST maintain a discoverable dependency tree for your systems](#you-must-maintain-a-discoverable-dependency-tree-for-your-systems)
 - [You MUST proactively identify vulnerabilities in dependencies with scanning and other tools](#you-must-proactively-identify-vulnerabilities-in-dependencies-with-scanning-and-other-tools)
-- [You MUST regularly update, replace and remove dependencies](#you-must-regularly-update-replace-and-remove-dependencies)
+- [You MUST regularly update, replace and remove dependencies](#you-must-regularly-update%2C-replace-and-remove-dependencies)
 
 ### You MUST assess the security of external components before introducing them into software designs
 

diff --git a/docs/standards/minimal-documentation-set-for-a-product.md b/docs/standards/minimal-documentation-set-for-a-product.md
@@ -20,7 +20,7 @@ A product should be documented to a minimum standard so that new engineers can b
 - [Product documentation MUST include a decision log](#product-documentation-must-include-a-decision-log)
 - [Product documentation MUST include incident management information](#product-documentation-must-include-incident-management-information)
 - [Product documentation MUST include information about observability](#product-documentation-must-include-information-about-observability)
-- [Product documentation MUST include build, release and deployment processes](#product-documentation-must-include-build-release-and-deployment-processes)
+- [Product documentation MUST include build, release and deployment processes](#product-documentation-must-include-build%2C-release-and-deployment-processes)
 
 ### Product documentation MUST include a description of the product and what it is for
 

diff --git a/docs/standards/standard.template.md b/docs/standards/standard.template.md
@@ -32,6 +32,8 @@ Internal links need to follow this format:
 [link text to internal page]({{ '/standards/writing-a-standard/' | url }})
 Note the use of the `url` filter. This ensures the link is appended to the base URL of the webpage correctly.
 
+Anchor tags, such as those used when listing the requirements at the top of the 'Requirements' section, should use HTML URL Encoding. This ensures links to headers with punctuation will work as expected. You can obtain the HTML URL Encodeded link by running the site locally, inspecting the appropriate <h3> element in the browser's developer tools and copying the value from the 'id' attribute.
+
 External links follow standard markdown formatting:
 [link text to external page](https://example.com)
 -->
@@ -40,7 +42,17 @@ External links follow standard markdown formatting:
 
 ## Requirement(s)
 
-<!-- Populate list for each requirement (there can be more than 2)-->
+<!-- Populate list for each requirement (there can be more than 2) -->
+
+<!--
+
+# Notes on anchor links
+
+Use HTML URL encoding as in the 'Notes on links' above, to ensure that links to headers with punctuation works as expected. For example:
+
+[Product documentation MUST include build, release and deployment processes](#product-documentation-must-include-build%2C-release-and-deployment-processes)
+
+-->
 
 - [Requirement 1](#requirement-1)
 - [Requirement 2](#requirement-2)