kestra-io / kestra-io/docs

ci: check built pages as Markdown for agents

Open
#5,664 1 comment 0 reactions 0 assignees View on GitHub
area/devops area/docs area/qa kind/website
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.