kestra-io / kestra-io/docs

[Docs] "Append .md to any kestra.io/docs/* URL" 404s on all 100 changelog pages

Open
#5,370 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

Every page under `/docs` renders this directive:

> For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. **Append `.md` to any `kestra.io/docs/*` URL for plain Markdown.**

`/llms.txt` repeats it for agents:

> **For agents and LLMs:** Append `.md` to any `kestra.io/docs/*` URL to retrieve that page as plain Markdown, or set `Accept: text/markdown` on the request.

The `.md` route does not exist for `/docs/changelog/*`. All 100 changelog pages in the sitemap return **HTTP 404**.

### Evidence

I checked every one of the 589 docs URLs in `/sitemap/docs.xml` with the `.md` suffix:

- 489 return `200 text/markdown`
- **100 return `404 text/html`** — every single `/docs/changelog/*` page, and nothing else

The content is not missing, only the route. The same URL served with an `Accept` header works:

```
curl -o /dev/null -w "%{http_code} %{content_type}\n" \
https://kestra.io/docs/changelog/v1.3.34.md
# 404 text/html

curl -H "Accept: text/markdown" -o /dev/null -w "%{http_code} %{content_type}\n" \
https://kestra.io/docs/changelog/v1.3.34
# 200 text/markdown
```

So the two documented access paths disagree with each other.

### Expected

Either `/docs/changelog/.md` returns the Markdown (consistent with the `Accept` header behavior and with the promise), or the directive is scoped to say which paths it covers.

### Why it matters

This is the entry point we advertise to agents and LLMs. An agent that trusts the documented pattern gets a 404 HTML error page for release notes — the pages most likely to be asked about right after a 2.0 release.

### Repro

```
for v in v1.3.34 v1.0.56 v0.22.46; do
curl -s -o /dev/null -w "%{http_code} %{content_type} $v\n" \
https://kestra.io/docs/changelog/$v.md
done
```

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the documented `.md` requests against `/docs/changelog/*` and compare them with the working `Accept: text/markdown` requests. Inspect the route handling for changelog pages and the `llms.txt` documentation; done means the documented access paths agree, with changelog `.md` URLs returning Markdown or the directive clearly scoped.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.