Alt text on all images, and a markdownlint pass over the repo

[enf0rc3]

Closes NES-235.

Why

NES-235 asks for alt text on our images, for accessibility and because it is a primary signal for search crawlers and AI search assistants. Every image in the docs now has it.

Adding alt text meant running markdownlint over the content, and once it was running, almost everything else it flagged was auto-fixable. So this does the whole repo in one go rather than leaving thousands of findings to surface a handful at a time in unrelated PRs. Worth doing once now, before the docs rewrites start, so the rewrites land on a clean baseline.

The safety net

NES-235 also asks for something to stop this regressing. That now exists without new tooling: CI already lints every .md and .mdx file a PR touches, and the repo passes clean, so MD045 fails any PR that adds an image without alt text.

One caveat. WCAG says genuinely decorative images should have empty alt, but MD045 requires alt on every markdown image. There was one such case — an inline help icon — and rather than invent a description, the sentence was reworded so the icon is the thing being named. A future decorative image needs an HTML <img alt=""> tag, which MD045 does not inspect.

What changed

Alt text on 534 images. Measured directly: the files in this diff contained 535 empty-alt images on main and contain one now — the deliberate before/after example in README.md. 12 built pages were still rendering alt="" after the first pass, because the include files in src/shared-content live outside src/pages and were never being linted. They are now.

Everything else markdownlint reported, nearly all of it mechanical: whitespace, emphasis style, blank lines around headings and lists, hard tabs, trailing newlines, table pipe alignment. Beyond the auto-fixable set, every fenced code block now declares a language, and a handful of heading levels were corrected so they increment by one.

List and heading structure are unchanged. Every ordered-list marker in the diff matches main exactly, indent and number, and no bold label was promoted to a heading. See the config notes below for why.

Wording is left alone apart from seven spelling corrections cspell flagged (Whilst to While, therefor to therefore, utilized to used, and similar), six bare here links given descriptive text, and the link and heading corrections listed under real bugs below.

Roughly 355 code blocks are labelled text, which gives them a visible "Text" chip in the block header. That is the existing convention — main already labels 275 blocks that way — but it is a visible change at this scale, so worth knowing before merge.

README.md documents the conventions, including the two auto-fixes below that are unsafe here, and the fact that src/shared-content needs linting too.

Config decisions

Six rules needed scoping or disabling rather than fixing. Each is a judgement call worth reviewing.

Four were rewriting authored structure rather than fixing faults, and are off:

• MD007 and MD005 (list indentation) → off. MD007 re-indented nested list items to its own 2-space default, flattening lines that were deliberately indented 4 spaces. The repo is mixed, so enforcing either width just churns files. Every bullet indent in the diff is back to what the author wrote.
• MD029 (ordered list prefix) → off. This one was breaking pages. Where a figure or code block sat at column 0 inside a numbered list, the parser ended the list, and MD029 "fixed" the follow-on items by restarting them at 1 — so rendered pages lost their step numbering. Numbering that deliberately runs across headings renders as <ol start="N">, which MD029 cannot express. Every ordered-list marker is restored, verified by aligning each changed file against main.
• MD036 (emphasis as heading) → off. It wanted 214 bold labels turned into headings. The level for each came from MD001 ratcheting rather than from meaning, so flat peers nested one level deeper each until they ran out at h6, and shared includes gained an h2 that popped a page outline back up when the include sat under an h3. It also pushed 214 entries into the on-page nav. Promoting a label to a heading is an information architecture decision rather than formatting, so it is left for a deliberate pass.

The other three are scoped rather than off:

• MD010 → code_blocks: false. 8,090 of the hard tabs are inside published script samples under src/shared-content/scripts. Retabbing code that users copy and run is worse than allowing tabs there. Tabs outside code blocks are still caught.
• MD024 → siblings_only. API reference pages legitimately repeat Parameters, Sample response and Properties under each endpoint. These are not siblings, and the rule still catches genuine duplicates within a section.
• MD051 → ignored_pattern: "^[a-z0-9-]*[A-Z]". The rule only recognises lowercase-kebab custom anchors, so it flags the 188 legacy {#PascalCase} anchors this site uses. Those anchors render and resolve correctly — verified against the rendered HTML. The pattern is anchored so it exempts that shape rather than any fragment with a capital in it.

The spelling dictionary is deliberately untouched

dictionary-octopus.txt has a code owner, and adding words to it would make this formatting PR wait on a review it does not otherwise need. It is unchanged here, and so is cspell.json.

None of the words cspell flagged were introduced by this PR — they are pre-existing prose that only got checked because spellcheck runs on changed files and this PR changes a lot of them. Touching a page for lint alone is enough to pull it into that job, so these failed regardless of whether anything was respelled.

No wording is changed. Each affected file carries a scoped exception next to the usage instead:

<!-- cspell:ignore SCCM -->

Fifteen words are handled this way: eksctl, mysqldump, authbind, Payara, SCCM, octopussamples, licensekey, tasklog, Linkback, Doesnt, Dbup, mytentacle, deregistering, gitversion and Springboot. The word is accepted only where it appears rather than repo-wide, and both dictionary-octopus.txt and cspell.json are untouched.

Several are genuinely worth correcting — Dbup is DbUp, Springboot is Spring Boot, mytentacle would read better as your-tentacle — but that is prose, not formatting, and it belongs in a follow-up the dictionary owner can review. This PR deliberately leaves the wording exactly as the authors wrote it.

One MDX page uses a YAML comment in its frontmatter instead of the HTML form, because MDX rejects <!-- --> and markdownlint reads {/* */} as emphasis markers.

Every other cspell finding was a genuine typo and was corrected.

Real bugs this surfaced

• /docs/octopus-rest-api linked to #api-clients, a section that does not exist on that page. Now points at the Octopus.Client page.
• The Azure accounts page had two sections with the same title and the same anchor. The second one actually documents federated credentials, and a link elsewhere on that page pointed at the anchor it should have had.
• kubernetes-resources.md carried a byte-identical duplicated Command section, and the probe sub-types sat at the same heading level as the probes themselves.
• An eksctrl link whose text contradicted its own URL, Springboot where the product is Spring Boot, and two dead link fragments in a shared include.
• Six bare here links replaced with descriptive text.

Two auto-fixes to avoid on this repo

Both are now documented in README.md:

• MD034 on .mdx. It rewrites bare URLs and email addresses as <url> autolinks. Valid CommonMark, but MDX parses the angle brackets as JSX and fails to compile. It broke the build twice here before being caught. Both cases are now explicit markdown links, and every .mdx has been swept for others.
• MD010 on tab-indented lists. It rewrites a leading tab as a single space, which is too shallow to nest the item, so the bullet silently escapes its parent. The 19 affected lines are now four spaces, matching what the tab rendered as.

Verification

Run locally against the whole repo, not just the changed files:

• markdownlint-cli2 over all 2,900 .md and .mdx files in the repo: 0 errors
• pnpm spellcheck: 0 issues, with no dictionary change
• 0 empty-alt images left in src, and 0 built pages rendering alt=""

Rebased onto main after 20 commits landed, including the heading-icon removal (#3354). Four content pages conflicted; those took main's version and the lint pass was re-run over them, so nothing from the newer commits is left behind. The nine markdown files those commits touched were checked individually — all images have alt text, no unlabelled code fences, no <url> autolinks in .mdx, and no tab-indented list items.

The indented figures were checked separately, since indenting a block can turn it into a code block: no :::figure or :::div text leaks into any built page, no image path ends up inside a <pre>, and rendered <figure> counts match the source image counts per page. main.css documents figures-inside-list-items as the intended layout.

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3358.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[enf0rc3]

Verification

This PR was reviewed in two passes: static analysis of the source diff, then a diff of the rendered HTML against production. The second pass is what mattered — it found regressions the first pass structurally could not see.

Why the rendered diff was necessary

Every regression found here left the file passing the linter. lint, spellcheck and build were green throughout. They only appear in the built page, so the diff is the only place to catch them.

Method: fetch all 639 changed doc pages from the preview environment and from octopus.com, reduce each to structural text (headings, <ol start>, <br>, code-block language, table cells, prose), and diff. 1,405 hunks were produced and every one was categorised — engine-level noise, intended change, or defect.

What it found — 12 regressions across 5 classes, all fixed

#	Class	Instances	Effect
1	MD029 list renumbering not fully reverted	~25 steps, 4 pages	Tutorial steps renumbered to 1. mid-sequence
2	MD036 bold→heading promotion	312 headings	False hierarchies down to ######; shared includes emitting ## inside ### sections
3	MD009 trimmed 3+ trailing spaces to zero	22 lines, 7 significant	Hard line breaks deleted; a 4-line definition list collapsed to one paragraph
4	MD039 removed spaces doing real work	5	likePuTTYgen, projectsand, CIDR format172.28.6.0/24
5	Table formatter inferred width from a malformed row	2 tables	Blank third column on /docs/insights/api

Plus: a scheme-less <www.…> autolink rendering literal angle brackets, two authored ### headings demoted to bold, and 5 mislabelled code fences (Terraform as xml/csharp, a CLI help listing as python).

Final state — verified against origin/main

Check	Result
Rendered ordered-list ordinals vs main	3 files differ, all fixes
Table column counts	0 changed
Hard line breaks	0 lost, 0 spuriously added
Headings demoted to bold	0
MD039 word joins	0
Anchor fragments	0 newly broken
Empty alt in src	0
<url> autolinks in .mdx	0
Accidental indented code blocks	0
Fence languages	0 suspects across 74 non-text assignments
/docs/insights/api cells	225, matching production table-for-table

dictionary-octopus.txt and cspell.json are byte-identical to main and absent from the diff.

Note on the diff baseline

aee3fac10 (unified → satteri) is in this PR's base but not yet on production, so 777 of the 1,405 hunks are that engine change, not this PR. Confirmed by running the same comparison on a page this PR doesn't touch: production drops <, & and && inside code blocks (List<string> renders as Liststring>) and satteri fixes it.

Lesson worth keeping

A formatter that normalises presentation should not infer structure. MD009 trimmed to zero because its rule is about trailing spaces, not about <br>. MD039 removed a space inside brackets without asking what the space separated. The table formatter measured the widest row because that is how you align columns — not because that row was correct.

README.md now documents MD009, MD010, MD034 and MD039 as auto-fixes to check by hand, with the point that ties them together: none of them show up as a lint failure afterwards.

Known gap, out of scope

CI lints only changed files, so MD045 guards alt text on any page a PR touches, but nothing re-checks all 2,901 files as a set. The clean baseline holds for edited pages and can drift elsewhere. A scheduled full-repo lint would close that — separate PR.