feat: add optional code linting tools and perform a lint pass

.editorconfig

@@ -0,0 +1,19 @@
+# EditorConfig docs: https://editorconfig.org/
+root = true
+
+# Default rules for all files.
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+# keep intentional trailing spaces for hard line breaks.
+trim_trailing_whitespace = false
+
+# YAML: 2-space indentation.
+[*.{yml,yaml}]
+indent_size = 2

.github/CODEOWNERS

@@ -7,5 +7,5 @@
 # review when someone opens a pull request.
 *       @tomcollins @BillyRuffian @chrilliams
 
-# All content 
+# All content
 /content/ @tomcollins @BillyRuffian @chrilliams

.github/pull_request_template.md

@@ -1,28 +1,47 @@
 ## Content Guidelines
 
-Post content must not include:
-
-- identifiers for production infrastructure e.g. IP addresses, network ranges, cloud provider IDs etc
-- data relating to real customers or staff members
+Post content must have a strong technical focus with other engineers being the primary audience.
+There are other communication channels for non-technical content and delivery or service updates such as [dvladigital.blog.gov.uk](https://dvladigital.blog.gov.uk/).
 
 ### Content Guidelines - Security
 
 Consider if the content of your post, including and images, has any security concerns:
 
 - would the information be revealing to an attacker?
 - is the content too revealing of backend processes?
-- do we need to make make specific details public?
+- do we need to make specific details public?
+
+Post content must not include:
+
+- identifiers for production infrastructure e.g. IP addresses, network ranges, cloud provider IDs etc
+- data relating to real customers or staff members
+
+If you have any doubt please seek support from the cybersecurity team before publishing your content.
+
+### Content Guidelines - Communication
+
+You must consider if the content of your post could cause damage to the reputation of the organisation.
+
+Your post content should not describe, or be directly related to:
+
+- changes that impact staff experience e.g. automation of work, changes to the types of work undertaken
+- changes that impact customers experience e.g. changes to customer process, customer waiting times
+- specific DVLA internal or external services
 
-If you have any doubt please seek support from the cyber security team before publishing your content.
+If you have any doubt please seek support from the [External Communications](mailto:external.comms@dvla.gov.uk) team before publishing your content.
 
-### Content Guidelines - Reputation
+### Content Guidelines - Accessibility
 
-You must consider if the content of your post could cause damage to the reputation of the organisation. 
+All content must be accessible to all users. This includes:
 
-If you have any doubt please seek support from the communications team before publishing your content.
+- using appropriate headings to structure content
+- using descriptive alt text or captions for images and figures
+- using descriptive link text for hyperlinks
+- using appropriate contrast for text and images
+- using helpful formatting such as lists and tables to structure content
 
-## Approval Process
+While not DVLA-specific, the GOV.UK Content and Publishing Service has some useful [guidance on formatting content](https://guidance.publishing.service.gov.uk/formatting-content/) to [be accessible and clear](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/tone-of-voice/clear-structure/).
 
-All changes to content must be approved by at least one person from the engineering review control group. This takes the form of a github pull request and is automatically enforced.
+Given our audience is primarily other engineers, consider the use of technical language and jargon.
 
-Formal approval within the wider organisation is not required by default but may be requested based on e.g. security or reputational concerns.
+Aim to use clear and concise language that is accessible to a wide range of readers, including those who may not be familiar with specific technologies or concepts.

.github/workflows/gh-pages.yml

@@ -41,4 +41,3 @@ jobs:
           publish_dir: ./public
           allow_empty_commit: true
 #           force_orphan: true
-

.gitignore

@@ -3,5 +3,12 @@ node_modules
 .DS_Store
 **/*/.DS_Store
 public
-.idea
+.idea/*
+!.idea/externalDependencies.xml
+!.idea/prettier.xml
+!.idea/codeStyles/
+!.idea/codeStyles/codeStyleConfig.xml
+!.idea/codeStyles/Project.xml
+!.idea/dictionaries/
+!.idea/dictionaries/project.xml
 resources

.markdownlint.yaml

@@ -0,0 +1,18 @@
+# Docs: https://github.com/DavidAnson/markdownlint/blob/main/README.md#configuration
+default: true
+
+# MD033/no-inline-html
+# Rule: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033---no-inline-html
+# Hugo shortcodes (e.g. {{< figure-a11y ... >}}) are treated as inline HTML by markdownlint.
+MD033: false
+
+# MD013/line-length
+# Rule: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
+# Avoid erroring on long URLs, shortcode lines, and code examples.
+MD013: false
+
+# MD041/first-line-heading/first-line-h1
+# Rule: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-headingfirst-line-h1
+# Front matter + optional title conventions in posts and pages mean that the first line of the markdown
+# file isn't always a heading, so disable this rule.
+MD041: false

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "_docs": "Prettier configuration docs: https://prettier.io/docs/configuration",
+  "printWidth": 120,
+  "proseWrap": "preserve",
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": false,
+  "trailingComma": "none"
+}

.run/Hugo_Build.run.xml

@@ -0,0 +1,13 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Hugo: Build" type="ShConfigurationType" factoryName="Shell Script">
+    <option name="SCRIPT_TEXT" value="hugo" />
+    <option name="SCRIPT_PATH" value="" />
+    <option name="SCRIPT_OPTIONS" value="" />
+    <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="INTERPRETER_PATH" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="EXECUTE_IN_TERMINAL" value="true" />
+    <option name="EXECUTE_SCRIPT_FILE" value="false" />
+    <method v="2" />
+  </configuration>
+</component>

.run/Hugo_Serve.run.xml

@@ -0,0 +1,13 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Hugo: Serve" type="ShConfigurationType" factoryName="Shell Script">
+    <option name="SCRIPT_TEXT" value="hugo server -D" />
+    <option name="SCRIPT_PATH" value="" />
+    <option name="SCRIPT_OPTIONS" value="" />
+    <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="INTERPRETER_PATH" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="EXECUTE_IN_TERMINAL" value="true" />
+    <option name="EXECUTE_SCRIPT_FILE" value="false" />
+    <method v="2" />
+  </configuration>
+</component>

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "budparr.language-hugo-vscode",
+    "editorconfig.editorconfig",
+    "davidanson.vscode-markdownlint",
+    "esbenp.prettier-vscode"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,33 @@
+{
+  "editor.formatOnSave": true,
+  "editor.detectIndentation": false,
+
+  "prettier.requireConfig": true,
+  "prettier.useEditorConfig": true,
+  "prettier.configPath": ".prettierrc.json",
+
+  "markdownlint.configFile": ".markdownlint.yaml",
+  "markdownlint.run": "onSave",
+
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.quickSuggestions": {
+      "comments": "on",
+      "strings": "on",
+      "other": "on"
+    }
+  },
+
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

.vscode/tasks.json

@@ -0,0 +1,28 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Hugo: Build",
+      "type": "shell",
+      "command": "hugo",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Hugo: Serve",
+      "type": "shell",
+      "command": "hugo server -D",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    }
+  ]
+}

README.md

@@ -4,22 +4,23 @@
 
 ## Content Guidelines
 
-Post content must have a strong technical focus with other engineers being the primary audience. There are other communication channels for non-technical content and delivery or service updates such as [dvladigital.blog.gov.uk](https://dvladigital.blog.gov.uk/).
+Post content must have a strong technical focus with other engineers being the primary audience.
+There are other communication channels for non-technical content and delivery or service updates such as [dvladigital.blog.gov.uk](https://dvladigital.blog.gov.uk/).
 
 ### Content Guidelines - Security
 
 Consider if the content of your post, including and images, has any security concerns:
 
 - would the information be revealing to an attacker?
 - is the content too revealing of backend processes?
-- do we need to make make specific details public?
+- do we need to make specific details public?
 
 Post content must not include:
 
 - identifiers for production infrastructure e.g. IP addresses, network ranges, cloud provider IDs etc
 - data relating to real customers or staff members
 
-If you have any doubt please seek support from the cyber security team before publishing your content.
+If you have any doubt please seek support from the cybersecurity team before publishing your content.
 
 ### Content Guidelines - Communication
 
@@ -33,6 +34,22 @@ Your post content should not describe, or be directly related to:
 
 If you have any doubt please seek support from the [External Communications](mailto:external.comms@dvla.gov.uk) team before publishing your content.
 
+### Content Guidelines - Accessibility
+
+All content must be accessible to all users. This includes:
+
+- using appropriate headings to structure content
+- using descriptive alt text or captions for images and figures
+- using descriptive link text for hyperlinks
+- using appropriate contrast for text and images
+- using helpful formatting such as lists and tables to structure content
+
+While not DVLA-specific, the GOV.UK Content and Publishing Service has some useful [guidance on formatting content](https://guidance.publishing.service.gov.uk/formatting-content/) to [be accessible and clear](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/tone-of-voice/clear-structure/).
+
+Given our audience is primarily other engineers, consider the use of technical language and jargon.
+
+Aim to use clear and concise language that is accessible to a wide range of readers, including those who may not be familiar with specific technologies or concepts.
+
 ## Approval Process
 
 All changes to content must be approved by at least one person from the engineering review control group. This takes the form of a github pull request and is automatically enforced.
@@ -72,3 +89,13 @@ git checkout master                   'ensure you are on the master branch'
 git pull                              'get latest changes from master branch'
 hugo server -D                        'starts site on localhost:1313'
 ```
+
+## Using Code Quality Tools
+
+This repo has been set up with the following developer tools to ensure code quality and consistency, with defaults set up for IntelliJ and VSCode users who have the relevant plugins installed.
+
+- [EditorConfig](https://editorconfig.org/) for consistent IDE configurations across different editors and IDEs (line endings, indentation, charset etc)
+- [Prettier](https://prettier.io/) for applying formatting rules automatically (e.g. line length, spacing etc)
+- [Markdownlint](https://github.com/DavidAnson/markdownlint) for applying markdown style rules that prettier can't pick up
+
+Tool or IDE usage is not enforced, but it is recommended to use these tools where possible to ensure consistency across the codebase and to avoid formatting inconsistencies when submitting pull requests.

archetypes/default.md

@@ -3,4 +3,3 @@ title: "{{ replace .Name "-" " " | title }}"
 date: {{ .Date }}
 draft: true
 ---
-

assets/css/extended/media.css

@@ -10,3 +10,8 @@
   margin-right: auto;
   width: auto;
 }
+
+.post-content figure audio {
+  /* Give the audio player some room to breathe */
+  margin: 1.5rem 0 1rem;
+}

content/open-source/index.md

@@ -4,7 +4,7 @@ date: 2023-02-27T18:03:22Z
 draft: false
 ---
 
-Ok so we don't code entirely [in the open](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open) at the DVLA we do like to share useful libraries and utilities when we can. You can find a list of recent open-source projects below.
+OK so we don't code entirely [in the open](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open) at the DVLA we do like to share useful libraries and utilities when we can. You can find a list of recent open-source projects below.
 
 ## AWS
 
@@ -58,13 +58,13 @@ This gem has pre-configured browser drivers that you can use out-of-the-box for
 
 Ka-Ping! An Idiomatic ruby way to construct ElasticSearch queries.
 
-# Dynamics 365
+## Dynamics 365
 
 ### [dataverse-helper](https://github.com/dvla/dataverse-helper)
 
 This gem helps you integrate with Microsoft Dynamics using Microsoft Dataverse Web API. You can create, retrieve, delete or update a record without worrying about authentications as it's automatically managed behind the scenes.
 
-# JavaScript
+## JavaScript
 
 ### [postman-paf-js](https://github.com/dvla/postman-paf-js)