fix(plugins): rewrite redirected docs links in API-sourced markdown

[vfanucci]

Plugin pages render markdown that comes from the API (schema property descriptions, plugin long descriptions, blueprint bodies). Those texts link to docs pages by URLs that have since moved, so every such link is a 301 for readers and a redirected inlink for crawlers.

The Screaming Frog crawl of 16 Sept lists ~400 of them, from three links repeated in the plugin templates:

• /docs/developer-guide/namespace-files → /docs/concepts/namespace-files (210 links)
• /docs/workflow-components/plugin-defaults → /docs/migration-guide/v2.0.0/plugin-defaults-removed (112)
• /docs/configuration-guide/plugins → /docs/configuration/plugins-and-execution (74)

The marked instances used by the markdown renderers now rewrite internal /docs/... links with the literal rules of src/contents/redirects/docs.yml (rules with capture groups or wildcards inside the path are skipped: they are 404 fallbacks and would rewrite live pages), and normalise /plugins/... links (lowercase, no .md). The rules file is read by line to keep the YAML library out of the hydrated islands.

Unit tests cover the rule filtering, the rewrite, and both marked instances.

[github-actions]

☁️ Cloudflare Worker Preview Deployed!

🔗 https://ks-fix-301-api-markdown-links-docs.kestra-io.workers.dev
🔗 https://850c780f-docs.kestra-io.workers.dev

🔦 Lighthouse Benchmark

Tested on 2026-09-16 17:12 UTC  ·  links point to https://ks-fix-301-api-markdown-links-docs.kestra-io.workers.dev
Compared against main baseline from 2026-09-16
Runner CPU index per shard: 2501, 2482, 4293, 2293 (baseline: 2334, deltas hidden on 5 page(s))

Scores (0–100, higher is better)

Page	Performance	Accessibility	Best Practices	SEO
Home	87	84	77	92
Get Started	60	83	77	100
Pricing	95	92	77	100
Enterprise	95	83	77	100
Cloud	88	80	77	100
About Us	86	91	77	100
Docs Landing	91	88	77	92
Contribute to Kestra (simple docs)	97	88	77	92
Flow (full featured docs)	94	90	77	92
Blog Index	69	91	77	100
Blog Post (sample)	96	88	77	100
VS Page (sample)	95	88	77	100
Plugins Landing	94	81	77	92
Plugin Page (sample)	98	88	77	100
Plugin Debug Page (sample)	82	88	77	100
Plugin Debug Return Page (sample)	88	88	77	100
Blueprints Landing	83	91	77	100
Blueprint Audit Logs CSV Export	82	92	77	100

Core Web Vitals (lower is better)

Page	LCP	FCP	TBT	CLS	Speed Index
Home	1.38 s	0.71 s	171 ms	0.101	1.46 s
Get Started	2.21 s	0.69 s	922 ms	0.000	1.26 s
Pricing	1.17 s	0.68 s	112 ms 🔻	0.000 🟢	1.24 s
Enterprise	1.34 s	0.67 s	101 ms	0.003	1.04 s
Cloud	2.22 s	0.67 s	81 ms 🔻	0.001	1.18 s
About Us	2.52 s	0.56 s	4 ms	0.000	0.89 s
Docs Landing	1.39 s	0.56 s	153 ms	0.001	1.53 s
Contribute to Kestra (simple docs)	1.14 s	0.60 s	19 ms	0.000	1.00 s
Flow (full featured docs)	1.14 s	0.66 s	143 ms	0.000	1.37 s
Blog Index	15.29 s	0.58 s	65 ms 🔻	0.000 🟢	2.43 s 🟢
Blog Post (sample)	1.31 s 🟢	0.63 s	42 ms 🟢	0.000	0.87 s
VS Page (sample)	1.26 s	0.62 s	90 ms	0.064	0.96 s
Plugins Landing	1.51 s	0.60 s	4 ms	0.000	1.35 s
Plugin Page (sample)	1.01 s	0.67 s	0 ms	0.000	1.00 s
Plugin Debug Page (sample)	0.97 s	0.62 s	363 ms	0.000	1.10 s
Plugin Debug Return Page (sample)	0.84 s	0.54 s	234 ms	0.000	1.65 s
Blueprints Landing	2.39 s	0.94 s	117 ms 🔻	0.000 🟢	1.53 s
Blueprint Audit Logs CSV Export	1.25 s	0.68 s	308 ms	0.000	1.60 s

Legend

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

Median of repeated runs: Home x5, About Us x3, Docs Landing x5, Flow (full featured docs) x3, Plugins Landing x3, Blueprints Landing x3. A single run of these swings 20+ points between runners.
The sample is measured across 4 parallel runners, so each page carries its own CPU index (Lighthouse's benchmarkIndex). Lighthouse does not normalise for host CPU, so a page's deltas are hidden when its runner differs from the baseline's by more than 10%.

View full Lighthouse HTML report for a page

Full per-page Lighthouse Results (LHR) are attached as the lhr-reports-shard-* artifacts on this run. Download and unzip one, 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.

[iitzIrFan]

The hook placement is correct and all API-sourced markdown paths go through it (schema descriptions via PluginsMarkdownRender, plugin long descriptions via OneHeader.astro, blueprint bodies). Tests, astro check and lint pass locally. Every to in the literal list exists in src/contents/docs.

The rewrite logic is wrong in one respect. docs.yml is a 404-fallback table (only applied by notFoundRedirect) that uses regexp anchoring for specificity. toLiteralRedirects treats exact-only rules (.../?$) and collapse rules (.../.*) the same as prefix rules. Verified by running rewriteRedirectedHref against the real file:

/docs/getting-started/contributing                                  => /docs/quickstart              (site: /docs/contribute-to-kestra)
/docs/getting-started/terraform                                     => /docs/quickstart              (site: /docs/terraform)
/docs/administrator-guide/configuration/enterprise-edition/secrets  => /docs/configuration           (site: /docs/concepts/secret)
/docs/plugin-developer-guide/task                                   => /docs/plugin-developer-guide  (live page, rewritten to its index)

The last one comes from line 109 ("/docs/plugin-developer-guide/.*" -> "/docs/plugin-developer-guide") and affects all eleven live children of that section. MarkdownRenderer also renders docs child cards, changelog bodies and AI chat answers, so this is not limited to plugin pages.

Blocking

1. src/markdown/redirectedLinks.ts: keep exactness. Return { from, to, prefix } from toLiteralRedirects, with prefix true only for (/.*)?, (.*)?, (.*) and .* tails, and only use startsWith in resolveLiteralRedirect when it is set. Test on the real file: /docs/getting-started/contributing -> /docs/contribute-to-kestra.
2. src/markdown/redirectedLinks.ts: skip rules where from === to (a self-targeting prefix rule can only be a fallback). Test: /docs/plugin-developer-guide/task unchanged.

Non-blocking

• Rule 181 has a fragment in to; the original suffix is appended after it: /docs/how-to-guides/cloudflare-r2#setup -> .../runtime-and-storage#cloudflare-r2#setup. Let the rule's fragment win and keep the query before it.
• Add a test that parseRedirectRules(raw) deep-equals YAML.parse(raw) for docs.yml. The line parser silently drops single-quoted or unquoted scalars, and nothing would catch that today.
• Trailing-slash stripping (/docs/x/ -> /docs/x) happens with no matching rule. Fine for trailingSlash: "never", but undocumented and untested.

Out of scope

• API text also links plugins with the old /plugins/plugin-aws/tasks/s3/... shape (seen in UploadFiles); those still 301 via redirectAlias.
• docs.yml has duplicate and conflicting rules (how-to-guides/ceph twice with different targets, administrator-guide/configuration three times).