Add a docs linter for silently-failing MDX mistakes (67 errors it already finds(!))

### Contributions

- [x] I have read the contribution docs, and understand what's expected of me.

### Link to the page on docs.getdbt.com requiring updates

Repo-wide -- the proposal adds one tooling script, and the content fixes touch the pages listed in the inventory below.

Tooling entry points:

- [website/scripts/lint-docs.js](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/scripts) (new) -- wired as `npm run lint:docs` and a step in [.github/workflows/lint.yml](https://github.com/dbt-labs/docs.getdbt.com/blob/current/.github/workflows/lint.yml).
- Data sources it reads: [constants.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/constants.js), [docs/terms/hover-terms.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/terms/hover-terms.md), [dbt-versions.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js), [availabilityPresets.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/availability/availabilityPresets.js), [lifeCycle/index.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/lifeCycle/index.js).

Every page with at least one finding (48 source files; the per-finding tables below have exact lines):

Docs:

- https://docs.getdbt.com/docs/build/documentation (unrecognised Lifecycle status `alpha`)
- https://docs.getdbt.com/docs/build/iceberg/about-catalogs (`` renders as nothing; the key is `acid`)
- https://docs.getdbt.com/docs/build/metricflow-time-spine (unrecognised Lifecycle status `Preview`)
- https://docs.getdbt.com/docs/build/ref-metrics-in-filters (single-line ```` ```...``` ```` fence that should be inline code)
- https://docs.getdbt.com/docs/build/view-documentation (unrecognised Lifecycle status `alpha` x2)
- https://docs.getdbt.com/docs/configuration-checklist (invalid availability `access: all_users`, so the access badge drops)
- https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp (unknown constant `cloud_cli` x2)
- https://docs.getdbt.com/docs/dbt-versions/2024-release-notes (unknown constant `copilot` x5, one broken image path)
- https://docs.getdbt.com/docs/dbt-versions/dbt-platform-release-notes-gen (unknown constants `copilot` x6 and `dev_agent`)
- https://docs.getdbt.com/docs/dbt-versions/release-notes (unknown constants `copilot` x4 and `dev_agent` x4)
- https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-platform-version (unknown constant `Fusion` x2 -- typo of `fusion`)
- https://docs.getdbt.com/docs/deploy/deploy-environments (broken image path)
- https://docs.getdbt.com/docs/deploy/deployments (source file `deployment-overview.md`; 2 broken image paths, unrecognised Lifecycle status `Preview` x2)
- https://docs.getdbt.com/docs/deploy/state-aware-setup (broken image path)
- https://docs.getdbt.com/docs/explore/data-health-signals (broken image path -- `.jpg` written for a `.png` on disk)
- https://docs.getdbt.com/docs/explore/data-tile (broken image path, unrecognised Lifecycle status `Legacy`)
- https://docs.getdbt.com/docs/explore/explore-projects (unrecognised Lifecycle status `Alpha` x3)
- https://docs.getdbt.com/docs/explore/model-query-history (broken image path)
- https://docs.getdbt.com/docs/local/connect-data-platform/watsonx-spark-setup (`` inside a code fence renders literally)
- https://docs.getdbt.com/docs/local/fusion-networking-requirements (unrecognised Lifecycle status `enterprise` -- token is `managed`)
- https://docs.getdbt.com/docs/platform/configure-dbt-cli (unknown constant `dbt_cli` -- typo of `platform_cli`)
- https://docs.getdbt.com/docs/platform/enable-dbt-ai (unknown constant `dbt_platform account` -- the next word leaked into the attribute)
- https://docs.getdbt.com/docs/upgrade-to-fusion-extension (unknown constant `copilot` x3)

Reference:

- https://docs.getdbt.com/reference/commands/cmd-docs (unrecognised Lifecycle status `alpha`)
- https://docs.getdbt.com/reference/commands/dbt-environment (`` inside a code fence renders literally)
- https://docs.getdbt.com/reference/dbt-jinja-functions/this (unknown constant `clou_ided` -- typo of `studio_ide`)
- https://docs.getdbt.com/reference/resource-configs/alias (`` inside a code fence -- symptom of a mismatched fence)
- https://docs.getdbt.com/reference/resource-configs/fabric-configs (unclosed ```` ```yaml ```` fence swallows the page tail)
- https://docs.getdbt.com/reference/resource-configs/invalidate_hard_deletes (unrecognised Lifecycle status `legacy`)
- https://docs.getdbt.com/reference/resource-configs/snapshots-jinja-legacy (unrecognised Lifecycle status `legacy`)
- https://docs.getdbt.com/reference/resource-properties/description (`` inside a code fence renders literally)

Guides:

- https://docs.getdbt.com/guides/analyze-your-data (source file `analyze-data-qs.md`; 3 broken image paths)
- https://docs.getdbt.com/guides/databricks-workflows (`` inside a code fence renders literally)
- https://docs.getdbt.com/guides/zapier-ms-teams (`` inside a code fence renders literally)
- https://docs.getdbt.com/guides/zapier-refresh-mode-report (`` inside a code fence x2)
- https://docs.getdbt.com/guides/zapier-refresh-tableau-workbook (`` inside a code fence x3)
- https://docs.getdbt.com/guides/zapier-slack (`` inside a code fence x2)

FAQs:

- https://docs.getdbt.com/faqs/Snapshots/snapshotting-freshness-for-one-source (`` inside a code fence renders literally)
- https://docs.getdbt.com/faqs/Troubleshooting/ide-session-unknown-error (`` inside a code fence renders literally)

Blog:

- https://docs.getdbt.com/blog/change-data-capture (6 images with empty `alt`)
- https://docs.getdbt.com/blog/star-sql-love-letter (1 image with empty `alt`)
- https://docs.getdbt.com/blog/financial-modeling-accounting-principles (9 images with empty `alt`)
- https://docs.getdbt.com/blog/demystifying-event-streams (6 images with empty `alt`)

Partials and config with no standalone URL (findings surface on every page that includes them):

- [docs/faqs/Accounts/_account-specific-features.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/faqs/Accounts/_account-specific-features.md) (18 Lifecycle plan display names -- `Enterprise`, `Enterprise+`, `Starter` -- where the tokens are `managed`, `managed_plus`, `self_service`)
- [snippets/_extension-requires-registration.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/snippets/_extension-requires-registration.md) (unknown constant `copilot`)
- [snippets/_mcp-qs-local.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/snippets/_mcp-qs-local.md) (unknown constant `dbt_core` -- typo of `core`)
- [snippets/_wizard-ide.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/snippets/_wizard-ide.md) (unknown constant `dbt_wizard` -- typo of `wizard`)
- [website/dbt-versions.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js) (4 `versionedPages` entries resolving to no doc, 1 `versionedCategories` label matching no sidebar category)

### What part(s) of the page would you like to see updated?

Several MDX components render nothing when given bad input instead of raising an error, so a mistake never fails `docusaurus build` and the reader just gets a corrupted page.

From what I can find:

1. [``](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/constant/index.js)
2. [``](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/term/index.js)

Both return `null` for an unknown name/id, so a typo silently deletes the word.

A component left inside a code fence renders literally (the [#9770](https://github.com/dbt-labs/docs.getdbt.com/issues/9770) class). An unclosed fence swallows the rest of the page into a code block. A `versionedPages` entry that points at a moved page silently drops its version gate. A `/img/` reference with the wrong extension renders a broken image. None of these fail the build.

I would like to propose adding a linter, `website/scripts/lint-docs.js`: which would check over `docs/`, `snippets/` and `blog/`, one CommonMark-style fence parser, and a small function per rule.

It generalises the existing `` check (folded in).

Errors exit non-zero listing `file:line [rule] reason`; warnings print but never fail CI.

Output looks like:

```sh
lint-docs: 67 error(s) found:

docs/reference/resource-configs/fabric-configs.md:229 [fence-balance] code fence opened with ``` is never closed (swallows the rest of the page)
docs/docs/build/iceberg/about-catalogs.md:46 [term-id] unknown term id "ACID" (renders as nothing; ids are case-sensitive keys of docs/terms/hover-terms.md)
docs/guides/zapier-slack.md:89 [component-in-fence] inside a code fence renders literally instead of being processed
dbt-versions.js:97 [versioned-page] versionedPages entry "docs/fusion/fusion" does not resolve to a doc under website/docs
...
```

I'd recommend making it a warning in CI first, but still run it, to see how it works against new PRs, once it's "trusted" (e.g. it actually works), make it required.

Run against `current` 2026-08-09 it reports 67 errors and 55 warnings. The errors are all real: 33 undefined constants, 15 components rendering literally in fences, 11 broken image paths (mostly a `.jpg` written for a `.png` that actually exists), 4 dead `versionedPages` gates, two malformed fences, one bad `access` value, and `id="ACID"` where the term key is `acid`.

You can see the branch here: https://github.com/dbt-labs/docs.getdbt.com/pull/9775

> DISCLAIMER: I wrote the list of checks I would like, then had Claude Code write the check js. I want to make that fully clear, as this is a prototype/proof of concept, and I would like to finalise the "checks"/"lints" before worrying too much about the implementation.

### Additional information

## Proposal for lint checks

Here's what I'm proposing checking:

1. [Fence balance](#fence-balance) -- fences left open at EOF, and `` ```...``` `` on one line that should be inline code.
2. [Unknown ``](#term-id) against the keys of `docs/terms/hover-terms.md`.
3. [Components (`Constant`, `Term`, `File`, ...) stranded inside a code fence](#component-in-fence).
4. Constants in frontmatter or `` props (neither is processed by MDX) -- no current hits.
5. [`` against `constants.js`](#constant-name) (the original check, folded in).
6. [`versionedPages` entries that resolve to no doc under `website/docs`](#versioned-page).
7. [`availability` frontmatter values against `availabilityPresets.js`](#availability).
8. [`/img/` paths that do not resolve under `website/static`](#image-path).
9. [Empty image `alt`](#empty-alt) -- warn only.
10. [`` tokens](#lifecycle) -- warn only, since an unknown status renders a plain grey pill with the literal text rather than vanishing.

Fenced code and inline code are blanked (newlines preserved, so line numbers stay exact) before the prose rules run, so a component shown as an example inside a fence is only ever reported by rule 3, never double-counted.

### Errors

67 total fail.

#### fence-balance

These are malformed code fences.

2 errors.

| File:line | Detail |
|---|---|
| [docs/docs/build/ref-metrics-in-filters.md#L227](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/build/ref-metrics-in-filters.md#L227) | Triple-backtick opens and closes on one line -- should be single-backtick inline code |
| [docs/reference/resource-configs/fabric-configs.md#L229](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/reference/resource-configs/fabric-configs.md#L229) | ```` ```yaml ```` never closed -- swallows the page tail (profiles.yml example, prose, the `dbt-utils` heading) into one code block |

#### term-id

These are unknown `` (case-sensitive keys of `hover-terms.md`).

1 error.

| File:line | Detail |
|---|---|
| [docs/docs/build/iceberg/about-catalogs.md#L46](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/build/iceberg/about-catalogs.md#L46) | `id="ACID"`; the key is `acid`, so the word disappears from the sentence |

#### component-in-fence

These are components stranded in a code fence render literally ([#9770](https://github.com/dbt-labs/docs.getdbt.com/issues/9770)).

MDX doesn't support this out-of-the-box.

15 errors.

| File:line | Component |
|---|---|
| [docs/docs/local/connect-data-platform/watsonx-spark-setup.md#L42](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/local/connect-data-platform/watsonx-spark-setup.md#L42) | `` |
| [docs/faqs/Snapshots/snapshotting-freshness-for-one-source.md#L16](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/faqs/Snapshots/snapshotting-freshness-for-one-source.md#L16) | `` |
| [docs/faqs/Troubleshooting/ide-session-unknown-error.md#L12](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/faqs/Troubleshooting/ide-session-unknown-error.md#L12) | `` |
| [docs/guides/databricks-workflows.md#L86](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/databricks-workflows.md#L86) | `` |
| [docs/guides/zapier-ms-teams.md#L100](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-ms-teams.md#L100) | `` |
| [docs/guides/zapier-refresh-mode-report.md#L63](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-refresh-mode-report.md#L63) | `` |
| [docs/guides/zapier-refresh-mode-report.md#L102](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-refresh-mode-report.md#L102) | `` |
| [docs/guides/zapier-refresh-tableau-workbook.md#L70](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-refresh-tableau-workbook.md#L70) | `` |
| [docs/guides/zapier-refresh-tableau-workbook.md#L108](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-refresh-tableau-workbook.md#L108) | `` |
| [docs/guides/zapier-refresh-tableau-workbook.md#L115](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-refresh-tableau-workbook.md#L115) | `` |
| [docs/guides/zapier-slack.md#L89](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-slack.md#L89) | `` |
| [docs/guides/zapier-slack.md#L232](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/zapier-slack.md#L232) | `` |
| [docs/reference/commands/dbt-environment.md#L41](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/reference/commands/dbt-environment.md#L41) | `` |
| [docs/reference/resource-configs/alias.md#L133](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/reference/resource-configs/alias.md#L133) | `` (symptom of a mismatched fence earlier in the file) |
| [docs/reference/resource-properties/description.md#L304](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/reference/resource-properties/description.md#L304) | `` |

#### versioned-page

These are `versionedPages` entries that resolve to no doc under `website/docs` (the version gate silently does nothing).

4 errors.

| File:line | Entry |
|---|---|
| [dbt-versions.js#L97](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js#L97) | `docs/fusion/fusion` |
| [dbt-versions.js#L101](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js#L101) | `docs/fusion/new-concepts` |
| [dbt-versions.js#L103](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js#L103) | `docs/fusion/fusion-networking` |
| [dbt-versions.js#L105](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js#L105) | `docs/fusion/telemetry` |

#### image-path

These are `/img/` references that do not resolve under `website/static` (`onBrokenLinks` doesn't cover images). Most are a `.jpg` written for a `.png` that exists on disk.

11 errors.

| File:line | Missing image |
|---|---|
| [docs/docs/dbt-versions/2024-release-notes.md#L326](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/dbt-versions/2024-release-notes.md#L326) | `/img/docs/dbt-platform/using-dbt-platform/example-triggers-section.png` |
| [docs/docs/deploy/deploy-environments.md#L88](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/deploy/deploy-environments.md#L88) | `/img/docs/collaborate/dbt-explorer/explore-staging-env.png` |
| [docs/docs/deploy/deployment-overview.md#L146](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/deploy/deployment-overview.md#L146) | `/img/docs/dbt-platform/deployment/deploy-scheduler.jpg` (disk has `.png`) |
| [docs/docs/deploy/deployment-overview.md#L148](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/deploy/deployment-overview.md#L148) | `/img/docs/dbt-platform/deployment/run-history.jpg` |
| [docs/docs/deploy/state-aware-setup.md#L68](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/deploy/state-aware-setup.md#L68) | `/img/docs/dbt-platform/using-dbt-platform/example-triggers-section.png` |
| [docs/docs/explore/data-health-signals.md#L6](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/explore/data-health-signals.md#L6) | `/img/docs/collaborate/dbt-explorer/data-health-signal.jpg` (disk has `.png`) |
| [docs/docs/explore/data-tile.md#L6](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/explore/data-tile.md#L6) | `/img/docs/collaborate/dbt-explorer/data-tile-pass.jpg` |
| [docs/docs/explore/model-query-history.md#L5](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/explore/model-query-history.md#L5) | `/img/docs/collaborate/dbt-explorer/model-query-queried-models.jpg` |
| [docs/guides/analyze-data-qs.md#L120](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/analyze-data-qs.md#L120) | `/img/analyst-walkthrough/insights-axis-title.png` |
| [docs/guides/analyze-data-qs.md#L130](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/analyze-data-qs.md#L130) | `/img/analyst-walkthrough/canvas-overview.png` |
| [docs/guides/analyze-data-qs.md#L134](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/guides/analyze-data-qs.md#L134) | `/img/analyst-walkthrough/canvas-commit.png` |

#### availability

These are frontmatter values not in the [availabilityPresets.js](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/availability/availabilityPresets.js) enums.

1 error.

| File:line | Detail |
|---|---|
| [docs/docs/configuration-checklist.md#L1](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/docs/configuration-checklist.md#L1) | `access: all_users` -- `all_users` is a preset name, not an `access` value, so the access badge silently drops |

#### constant-name

These are `` that aren't a key of `constants.js` (renders as nothing).

This was the original find that gave me the idea for a linter.

33 errors.

| Name | Count | Fix |
|---|---|---|
| `copilot` | 18 | New `constants.js` entry needed (naming call, presumably `dbt Copilot`) |
| `dev_agent` | 6 | New `constants.js` entry needed |
| `Fusion` | 2 | Typo of `fusion` |
| `cloud_cli` | 2 | Typo of `platform_cli` |
| `dbt_cli` | 1 | Typo of `platform_cli` |
| `dbt_core` | 1 | Typo of `core` |
| `dbt_wizard` | 1 | Typo of `wizard` |
| `clou_ided` | 1 | Typo of `studio_ide` |
| `dbt_platform account` | 1 | The next word leaked into the attribute -- should be `dbt_platform` |

Mostly in the release-notes pages:

- `release-notes.md` (8)
- `dbt-platform-release-notes-gen.md` (7)
- `2024-release-notes.md` (5)
- `upgrade-to-fusion-extension.md` (3)
- plus `upgrade-dbt-platform-version.md`, `setup-local-mcp.md`, `configure-dbt-cli.md`, `enable-dbt-ai.md`, `this.md`, and three snippets.

Live example: [release-notes](https://docs.getdbt.com/docs/dbt-versions/release-notes) reads `always available in the dbt and no longer requires a feature flag` -- the `copilot`/`dev_agent` words and their link have vanished.

### Warnings

55 total, all non-blocking.

These print for visibility but never fail CI, because the output degrades rather than vanishing.

#### lifecycle

`` tokens the [component](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/src/components/lifeCycle/index.js) doesn't recognise; each renders a plain grey pill with the literal text instead of the styled/linked pill.

32 warnings.

| Token | Count | Note |
|---|---|---|
| `Enterprise+` | 9 | Plan display name; the token is `managed_plus` |
| `Enterprise` | 8 | Plan display name; the token is `managed` |
| `alpha` / `Alpha` | 4 / 3 | No `alpha` status exists in the component |
| `Preview` | 3 | Case typo of `preview` |
| `legacy` / `Legacy` | 2 / 1 | No `legacy` status token exists |
| `Starter` | 1 | Plan display name; the token is `self_service` |
| `enterprise` | 1 | Should be `managed` |

Most are in [docs/faqs/Accounts/_account-specific-features.md](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/docs/faqs/Accounts/_account-specific-features.md) (plan display names throughout), plus `explore-projects.md`, `view-documentation.md`, `deployment-overview.md`, `metricflow-time-spine.md`, and others.

#### empty-alt

These are markdown images with an empty `alt`, all in four older blog posts: `leverage-accounting-principles...` (9), `demystifying-event-streams` (6), `change-data-capture` (6), `star-sql-love-letter` (1).

22 warnings.

#### versioned-category

[dbt-versions.js#L213](https://github.com/dbt-labs/docs.getdbt.com/blob/current/website/dbt-versions.js#L213): `versionedCategories` entry `Install dbt Core` matches no category label in `sidebars.js` (best-effort check).

1 warning.

## Additional information

- Companion issue [#9770](https://github.com/dbt-labs/docs.getdbt.com/issues/9770) and the MDX maintainers' [discussion 2288](https://github.com/orgs/mdx-js/discussions/2288) cover the components-in-code-fences root cause (by design in MDX). The `component-in-fence` rule catches every current instance.
- The linter is intentionally red on merge -- catching these is the point -- but that means sequencing. Options, take whichever you prefer:
1. I follow up with content-fix PRs -- the fence, term, image-extension, `versionedPages` and Lifecycle-token fixes are mechanical; the undefined constants (`copilot` / `dev_agent`) need a naming call from dbt Labs before I can add the `constants.js` entries.
2. You fix the content first and the linter lands after, green.
3. The check starts life as a non-blocking step until the inventory is worked down, then becomes required.
- Severity split is deliberate: silent deletions and broken output are errors; degraded-but-visible output (grey Lifecycle pill, empty alt) is a warning so it never blocks a merge.

Start by reviewing the proposed website/scripts/lint-docs.js entry point, the existing Constant and Term components, their data sources, and .github/workflows/lint.yml. Run the proposed npm run lint:docs command against the listed docs, snippets, blog, and dbt-versions.js inputs; done means the agreed checks produce actionable file:line output and the intended CI warning or failure behavior.

Written by the indexing model from the issue text.