ci: check built pages as Markdown for agents
- Dominant language
- Astro
- Stars
- 155
- Forks
- 177
- Avg merge
- 1d 20m
- Merged PRs (30d)
- 192
Description
Part of the Markdown for Agents Phase 1 epic (see #5652). kestra.io has Cloudflare Markdown for Agents enabled: `Accept: text/markdown` converts the SSR HTML at the edge, so defects in the HTML end up in what AI agents read. Cloudflare strips `nav`/`header`/`footer`/scripts/styles/inline SVG, ignores `aria-hidden` and empty `alt`, keeps `.visually-hidden` text and `display:none` content, and renders `
- ` as separate lines (all verified on production).
## Goal
A small guardrail mirroring `scripts/check-dist-asset-links.mjs` and its vitest in `src/utils/checkDistAssetLinks.test.ts`.
## Scope
- `scripts/check-dist-markdown.mjs` exporting a pure `checkMarkdown(md, rules)`, converting `dist/client/{index,pricing/index,enterprise/index}.html` with `node-html-markdown` (devDependency; closest to Cloudflare's inline-concatenation and table output; ignore `nav`, `header`, `footer`, `style`, `svg`, non-JSON-LD `script`).
- Rules: pricing feature rows have both plan cells filled; no `0+ Plugins`; six blockquotes on `/`; no line over 2,000 chars on `/`; first heading within 15 lines; size under the agreed threshold (local output is ~15% smaller than Cloudflare's because URLs are relative, document this).
- `--url` mode running the same rules against `https://kestra.io/...` with `Accept: text/markdown` for post-deploy verification.
- Step in `.github/workflows/deploy.yml` after the dangling-asset check. Report-only until the fix PRs land, then strict.
## Done when
- Vitest fixtures cover pass and fail for each rule.
- The deploy job fails on a regression of any rule.
Contributor guide
Research direction
Start by reading scripts/check-dist-asset-links.mjs and src/utils/checkDistAssetLinks.test.ts, then inspect .github/workflows/deploy.yml and the listed dist/client HTML pages. Add the Markdown conversion checks and Vitest pass/fail fixtures for each rule, including --url behavior. Done means the deploy job runs the checks and fails on regressions after the report-only phase ends.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, javascript, markdown, node.js
- Domain
- ci-cd, documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100