CI: validate snippet MDX frontmatter and asset references #136

New issue

Closed

opened 2026-04-19 11:03:02 +00:00 by pokebedrock-bot · 1 comment

pokebedrock-bot commented

2026-04-19 11:03:02 +00:00

(Migrated from github.com)

Summary

npm run lint currently validates frontmatter and local image references for regular docs, but both custom validators explicitly skip docs/**/snippets/**.

Evidence

On current main, I created a temporary local repro file under docs/en/snippets/__tmp-validation-gap.mdx with:

an unquoted YAML date (lastUpdated: 2026-04-19), which the schema rejects for normal docs
a broken local image reference (![image](../assets/does-not-exist.png))

Even with that file present, the repo's current validators still passed:

> npm run lint:frontmatter:run
Validated 30 markdown files.

> npm run lint:images:run
Image validation succeeded for 30 docs.

That proves snippet MDX currently sits outside the frontmatter + image validation gate even though snippet files in this repo already carry frontmatter metadata and can contain importable content.

Impact

A broken snippet can land on main without CI noticing:

schema-invalid snippet metadata can drift from the rest of the docs corpus
stale/missing local images inside snippets are not caught before merge
imported reusable content becomes a silent failure surface compared with normal docs

Acceptance criteria

scripts/validate-frontmatter.ts validates regular docs plus docs/**/snippets/**
scripts/check-images.ts validates regular docs plus docs/**/snippets/**
_partials remain excluded unless/until they gain a consistent validation contract
npm run lint fails when a snippet MDX file has invalid frontmatter or a broken local image reference

## Summary `npm run lint` currently validates frontmatter and local image references for regular docs, but both custom validators explicitly skip `docs/**/snippets/**`. ## Evidence On current `main`, I created a temporary local repro file under `docs/en/snippets/__tmp-validation-gap.mdx` with: - an unquoted YAML date (`lastUpdated: 2026-04-19`), which the schema rejects for normal docs - a broken local image reference (`![image](../assets/does-not-exist.png)`) Even with that file present, the repo's current validators still passed: ```text > npm run lint:frontmatter:run Validated 30 markdown files. > npm run lint:images:run Image validation succeeded for 30 docs. ``` That proves snippet MDX currently sits outside the frontmatter + image validation gate even though snippet files in this repo already carry frontmatter metadata and can contain importable content. ## Impact A broken snippet can land on `main` without CI noticing: - schema-invalid snippet metadata can drift from the rest of the docs corpus - stale/missing local images inside snippets are not caught before merge - imported reusable content becomes a silent failure surface compared with normal docs ## Acceptance criteria - `scripts/validate-frontmatter.ts` validates regular docs plus `docs/**/snippets/**` - `scripts/check-images.ts` validates regular docs plus `docs/**/snippets/**` - `_partials` remain excluded unless/until they gain a consistent validation contract - `npm run lint` fails when a snippet MDX file has invalid frontmatter or a broken local image reference

smell-of-curry commented

2026-10-06 16:04:06 +00:00

Owner

Already fixed on main by af00d16 (PR #137). scripts/validate-frontmatter.ts and scripts/check-images.ts no longer ignore **/snippets/**. _partials stay excluded. Current frontmatter ignore is _partials, node_modules, and README.md; the image ignore is _partials and node_modules.

Already fixed on `main` by `af00d16` (PR #137). `scripts/validate-frontmatter.ts` and `scripts/check-images.ts` no longer ignore `**/snippets/**`. `_partials` stay excluded. Current frontmatter ignore is `_partials`, `node_modules`, and `README.md`; the image ignore is `_partials` and `node_modules`.

smell-of-curry closed this issue

2026-10-06 16:04:07 +00:00