Add a note about linting

README.md

@@ -52,6 +52,32 @@ The most common failures are:
 - A new image is referenced with the wrong path
 - An internal link has a bad address
 
+### Markdown linting
+
+Markdown files are linted in CI using [markdownlint](https://github.com/DavidAnson/markdownlint). The rules are configured in `.markdownlint.json`.
+
+To catch issues locally, install the [markdownlint VS Code extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) (already included in the recommended extensions). It will highlight errors on save.
+
+You can also run the linter from the command line using [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2):
+
+```bash
+npx markdownlint-cli2 "src/pages/**/*.{md,mdx}"
+```
+
+To lint only files changed in the current branch (matching the CI behavior):
+
+```bash
+git diff origin/main --name-only --diff-filter=ACMRTUXB -- '*.md' '*.mdx' | xargs npx markdownlint-cli2
+```
+
+Or in PowerShell:
+
+```powershell
+git diff origin/main --name-only --diff-filter=ACMRTUXB -- '*.md' '*.mdx' | ForEach-Object { npx markdownlint-cli2 $_ }
+```
+
+Common issues include missing blank lines around headings, fenced code blocks without a language, duplicate headings, and trailing whitespace.
+
 ### Spell check
 
 You can run the spell check locally using:
@@ -86,7 +112,7 @@ Before merging to `main` it's possible you'd like to see your changes in a previ
 
 You can generate a static copy of the site using `pnpm build` and run it in a browser with `pnpm preview`.
 
-Note! We use _Sharp_ to generate images. You may need to install a specific flavour of _Sharp_ depending on your operating system. If you see an error, such as "Error: Could not load the "sharp" module using the linux-x64 runtime", you can follow the instruction on the [Sharp cross-platform page](https://sharp.pixelplumbing.com/install#cross-platform). You can also refer to [issue 2142](https://github.com/OctopusDeploy/docs/issues/2142).
+Note! We use *Sharp* to generate images. You may need to install a specific flavour of *Sharp* depending on your operating system. If you see an error, such as "Error: Could not load the "sharp" module using the linux-x64 runtime", you can follow the instruction on the [Sharp cross-platform page](https://sharp.pixelplumbing.com/install#cross-platform). You can also refer to [issue 2142](https://github.com/OctopusDeploy/docs/issues/2142).
 
 ## Astro hints and tips
 
@@ -205,7 +231,7 @@ MDX files don't allow short-form links, instead of using `<https://example.com>`
 
 ### Title icons
 
-If you are updating a page in Docs which doesn't already have a title icon, please add one. Title icons can be added in the frontmatter for each page by adding a Font Awesome class in the `icon` entry: 
+If you are updating a page in Docs which doesn't already have a title icon, please add one. Title icons can be added in the frontmatter for each page by adding a Font Awesome class in the `icon` entry:
 
 ```yaml
 ---