fix(docs): serve changelog pages as Markdown at .md URLs

[vfanucci]

Problem

Every /docs/changelog/*.md URL returns a 404 HTML error page, while the same URL without the extension returns 200.

I checked all 591 docs URLs in sitemap/docs.xml:

Result	Count
200 + text/markdown	490
404 + text/html	101

All 101 failures are the changelog namespace — the index (/docs/changelog.md) plus its 100 release pages (v0.22.41 → v1.3.36). No other docs URL is affected.

This breaks a contract the site advertises in two places:

• DocsLayout.astro — "Append .md to any kestra.io/docs/* URL for plain Markdown."
• llms-full.txt.ts — same statement

So an AI agent that follows the documented instruction gets a 404 on every single release note.

Cause

The catch-all route src/pages/docs/[...docsPath].md.ts builds its paths from getCollection("docs"), i.e. the Markdown files in this repo. Changelog pages are built from the GitHub releases API in src/pages/docs/changelog/[tag].astro and belong to no content collection, so no .md path was ever emitted for them.

Fix

• src/pages/docs/changelog/[tag].md.ts — mirrors the getStaticPaths of [tag].astro (same fetchMajorReleases source and 150 limit), so every release page that gets built also gets a Markdown endpoint
• src/pages/docs/changelog.md.ts — the index, listing every release with its date and page URL, as a discovery entry point
• src/utils/changelogMarkdown.ts — rendering extracted so it is unit-testable, keeping the routes thin
• src/utils/changelogMarkdown.test.ts — 6 tests (name/tag fallback, missing body, missing date, empty release list)

Both endpoints return text/markdown; charset=utf-8, matching the existing docs.md.ts and [...docsPath].md.ts pattern. Release bodies keep the commit-link rewriting already done by fetchMajorReleases.

Verification

Against the local dev server, replaying the exact 101 URLs that 404 in production:

• 99/101 → 200 text/markdown
• 2 remaining (v1.2.3, v0.23.27) 404 in both HTML and .md — they have dropped out of the GitHub API response window, so their .astro pages 404 too. Unrelated to this change; see follow-up below.

Spot-checked output of /docs/changelog/v1.3.35.md (h1, sections, rewritten commit links, contributors) and /docs/changelog.md (100 dated release links). vitest run: 10 files / 79 tests passing. oxlint clean.

Follow-ups (not in this PR)

1. The changelog is absent from llms.txt and llms-full.txt (0 occurrences of docs/changelog in either). Release notes remain invisible to LLM consumers even with these endpoints live; they should be listed.
2. fetchMajorReleases(150) requests per_page=150, but the GitHub API caps per_page at 100. Only ~100 release pages are ever built, so older changelog URLs silently start 404ing as new releases ship — including URLs that were in the sitemap and may be linked externally. Worth pagination or a redirect strategy.

🤖 Generated with Claude Code

[github-actions]

☁️ Cloudflare Worker Preview Deployed!

🔗 https://ks-fix-changelog-markdown-endpoin-docs.kestra-io.workers.dev
🔗 https://b108eaa4-docs.kestra-io.workers.dev

🔦 Lighthouse Benchmark

Tested: http://localhost:8787 on 2026-09-01 12:31 UTC
Compared against main baseline from 2026-09-01

Scores (0–100, higher is better)

Page	Performance	Accessibility	Best Practices	SEO
Home	85	84	54	92
Get Started	63	83	54	100
Pricing	98	92	54	100
Enterprise	96	83	54	100
Cloud	94	80	54	100
About Us	98 🟢 +15	91	54	100
Docs Landing	95	88	54	92
Contribute to Kestra (simple docs)	98	88	54	92
Flow (full featured docs)	91	90	54	92
Blog Index	65	91	54	100
Blog Post (sample)	90	88	54	100
VS Page (sample)	98	88	54	100
Plugins Landing	93	81	54	92
Plugin Page (sample)	93	88	54	100
Plugin Debug Page (sample)	96	88	54	100
Plugin Debug Return Page (sample)	95	88	58	100
Blueprints Landing	79	91	54	92
Blueprint Audit Logs CSV Export	0	0	0	0

Core Web Vitals (lower is better)

Page	LCP	FCP	TBT	CLS	Speed Index
Home	1.20 s	0.65 s	256 ms	0.001 🟢	1.69 s
Get Started	2.08 s	0.64 s	780 ms	0.000	0.90 s
Pricing	1.02 s	0.58 s	40 ms 🔻	0.000	0.72 s
Enterprise	1.35 s	0.62 s	43 ms 🔻	0.000 🟢	0.77 s
Cloud	1.63 s	0.61 s	41 ms	0.000 🟢	0.83 s
About Us	1.01 s 🟢	0.63 s	33 ms 🔻	0.000	0.81 s
Docs Landing	1.17 s 🔻	0.60 s	114 ms 🔻	0.000 🟢	1.20 s
Contribute to Kestra (simple docs)	1.03 s	0.55 s	49 ms	0.003	0.79 s
Flow (full featured docs)	1.71 s 🔻	0.55 s	125 ms 🔻	0.000	1.08 s
Blog Index	9.69 s	0.56 s	28 ms	0.000 🟢	7.61 s 🟢
Blog Post (sample)	2.11 s	0.57 s	39 ms 🔻	0.000	0.73 s
VS Page (sample)	1.14 s	0.63 s	37 ms	0.000 🟢	0.71 s
Plugins Landing	1.02 s	0.62 s	60 ms	0.000	2.41 s
Plugin Page (sample)	1.02 s	0.68 s	125 ms 🔻	0.000	1.98 s
Plugin Debug Page (sample)	0.92 s	0.62 s	56 ms 🔻	0.000	1.75 s
Plugin Debug Return Page (sample)	1.01 s	0.65 s	68 ms 🟢	0.000	1.92 s
Blueprints Landing	2.41 s	0.94 s	51 ms 🔻	0.000	3.12 s
Blueprint Audit Logs CSV Export	0.00 s	0.00 s	0 ms	0.000	0.00 s

Legend

🟢 improved  ·  🔻 regressed  ·  (blank) no significant change
Score threshold: ±10 pts  ·  Metric threshold: ±30% of baseline

View full Lighthouse HTML report for a page

Full per-page Lighthouse Results (LHR) are attached as the lhr-reports artifact on this run. Download and unzip it, then open https://googlechrome.github.io/lighthouse/viewer/ and drop the <page>-lhr.json file into the page to see every audit, opportunity, and diagnostic.

[vfanucci]

https://kestra.io/docs/changelog/$v.md