kestra-io / kestra-io/docs

[Bash2.0][Docs] Markdown served to agents contains 949 unresolvable source-tree links across 247 pages

Open
#5,371 0 comments 0 reactions 0 assignees View on GitHub
area/docs kind/website
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.