kestra-io / kestra-io/docs

[Bash2.0][Docs] API reference operations have no anchors — 8 deep links from the API guide silently land at the top of the page

Open
#5,375 0 comments 0 reactions 0 assignees View on GitHub
area/docs area/frontend kind/website
Dominant language
Astro
Stars
155
Forks
177
Avg merge
1d 20m
Merged PRs (30d)
192

Description

### What's wrong

`/docs/how-to-guides/api` links to individual operations on `/docs/api-reference/open-source` using fragment anchors. None of those anchors exist, so all 8 links scroll nowhere and the reader is dropped at the top of a ~12,000px page with no indication anything went wrong.

The 8 links, all from `/docs/how-to-guides/api`:

```
#post-/api/v1/flows
#post-/api/v1/executions/-namespace-/-id-
#get-/api/v1/executions/-executionId-
#put-/api/v1/namespaces/-namespace-/kv/-key-
#get-/api/v1/namespaces/-namespace-/kv/-key-
#get-/api/v1/namespaces/-namespace-/files
#get-/api/v1/namespaces/-namespace-/files/directory
#post-/api/v1/namespaces/-namespace-/files
```

### Evidence

On a fully hydrated `/docs/api-reference/open-source#post-/api/v1/flows`:

```js
location.hash // "#post-/api/v1/flows"
document.getElementById("post-/api/v1/flows") // null
window.scrollY // 0 — no scroll happened
document.querySelectorAll("h2, h3").length // 1
```

The only heading and only content anchor on the whole page is `explore-the-kestra-open-source-api`. The operations render inside a web component whose internals are not exposed to the page, so:

1. **No operation is linkable.** Not from the docs, not from a support reply, not from a shared URL.
2. **The Table of Contents shows a single entry** — "Explore the Kestra Open Source API" — for the entire API reference. Every visible section (Flows, Executions, Triggers, Namespaces, Blueprints) is absent from it.
3. **Browser find-in-page does not match endpoint paths**, because `document.body.innerText` contains zero `/api/v1/` strings even though they are on screen.

### Expected

Each operation gets a stable `id` in the light DOM, matching the anchors the docs already link to, and each section registers with the Table of Contents.

### Note

Possibly related to #5353 (left TOC), but that issue is about the left navigation on regular docs pages; this is the right-hand TOC plus the missing operation anchors on the API reference specifically. Happy to have them merged if the root cause turns out to be shared.

### Repro

1. Open https://kestra.io/docs/how-to-guides/api
2. Click the "POST endpoint" link in the "Create a Flow" section
3. The API reference page loads at the top; nothing scrolls to `POST /api/v1/flows`
4. Check the Table of Contents on the right — one entry for the whole API

Contributor guide

Open the contributing guide

Research direction

Start with the `/docs/how-to-guides/api` links and the `/docs/api-reference/open-source` page, then inspect the API reference web component that renders the operations. Verify how its sections and the right-hand Table of Contents are registered; done means all 8 existing fragments resolve to stable light-DOM ids and each visible section appears in the TOC.

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
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.