[Bash2.0][Docs] Markdown served to agents contains 949 unresolvable source-tree links across 247 pages
- Dominant language
- Astro
- Stars
- 155
- Forks
- 177
- Avg merge
- 1d 20m
- Merged PRs (30d)
- 192
Description
### What's wrong
The Markdown returned by `.md` (and reproduced in `/llms-full.txt`) keeps the **build-time source paths** for internal links instead of rewriting them to site URLs.
From `https://kestra.io/docs/tutorial/fundamentals.md`:
```
If you haven't already, follow the [Quickstart Guide](../../01.quickstart/index.md)
or check the detailed [Installation Guide](../../02.installation/index.mdx).
```
Those directories (`01.quickstart`, `02.installation`) are repo paths with numeric ordering prefixes. They do not exist as URLs, so every one of these links is dead for any consumer of the Markdown.
### Evidence
Across the 489 docs pages that serve Markdown:
- **247 pages (50.5%)** contain at least one of these links
- **949 links total**
- `/llms-full.txt` contains the same **949**
Most frequent targets:
| Count | Link |
|---|---|
| 23 | `../../06.concepts/04.secret/index.md` |
| 18 | `../../05.workflow-components/06.outputs/index.md` |
| 12 | `../../06.concepts/05.kv-store/index.md` |
| 12 | `../../07.enterprise/02.governance/secrets-manager/index.md` |
| 11 | `../../16.scripts/06.outputs-metrics/index.md` |
Every resolution attempt 404s:
```
curl -s -o /dev/null -w "%{http_code}\n" https://kestra.io/docs/01.quickstart/index.md
# 404
curl -s -o /dev/null -w "%{http_code}\n" https://kestra.io/docs/05.workflow-components/01.flow/index.md
# 404
```
### Expected
The Markdown renderer should apply the same link transform the HTML build applies — `../../01.quickstart/index.md` becomes `/docs/quickstart` (or the absolute URL). The rendered HTML page gets this right; only the Markdown output does not.
### Why it matters
`/llms.txt` presents this Markdown as the canonical machine-readable docs. An agent that follows a citation lands on a 404 half the time, which reads to the user as Kestra's docs being broken.
### Repro
```
curl -s https://kestra.io/docs/best-practices/credentials-vs-secrets-vs-kv-store.md \
| grep -oE '\]\([^)]*[0-9]{2}\.[a-z0-9-]+/[^)]*\.mdx?\)'
```
Contributor guide
Research direction
Reproduce the problem with the provided curl command and compare the Markdown renderer with the HTML build's link transform. Trace how .md and /llms-full.txt are generated, then verify that numeric source-tree links resolve to site URLs and no longer produce 404s.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100