kestra-io / kestra-io/docs

[Bash2.0][Docs] .md output uses the SEO <title> as the H1 instead of the page's real H1, on 485 of 489 pages

Open
#5,377 4 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 served at `.md` opens with a `#` heading taken from the HTML `` tag rather than the page's actual `<h1>`. The two are written for different purposes and almost never match.

`https://kestra.io/docs/tutorial/fundamentals`:

| Source | Heading |
|---|---|
| Page `<h1>` (what a reader sees) | Create Your First Hello World Flow |
| `.md` first line | `# Build a Hello World Flow in Kestra` |
| `<title>` tag | Build a Hello World Flow in Kestra \| Kestra |

More:

| Page | Page H1 | `.md` H1 |
|---|---|---|
| `/docs` | Welcome to Kestra | Kestra Docs: Your Infinitely-Scalable Orchestration Platform |
| `/docs/administrator-guide` | Everything you need to operate and secure your Kestra cluster | Administrator Guide: Operate and Secure Your Cluster |
| `/docs/administrator-guide/monitoring` | Set up alerts and monitor your Kestra instance in production | Kestra Monitoring: Prometheus, Alerts, and Health Checks |
| `/docs/administrator-guide/custom-ca-kubernetes` | Trust a custom CA for outbound connections on Kubernetes | Adding a Self-Signed Certificate to Kestra on Kubernetes |

### Evidence

Comparing the `.md` H1 against the rendered `<h1>` for all 489 pages that serve Markdown:

- **485 pages (99.2%) differ**
- In **all 485**, the `.md` H1 is exactly the `<title>` with the ` | Kestra` suffix removed

So this is systematic, not scattered authoring drift.

### Expected

The Markdown H1 should be the page's `<h1>`. If the SEO title is worth carrying, it belongs in frontmatter (`title:`), which the Markdown output already emits for some routes — not as the document's only heading.

### Why it matters

An agent that answers "per the Kestra docs page *Kestra Monitoring: Prometheus, Alerts, and Health Checks*…" is naming a heading the user will not find when they open the page. It quietly breaks the human's ability to verify the machine.

### Repro

```
curl -s https://kestra.io/docs/tutorial/fundamentals.md | head -1
# → # Build a Hello World Flow in Kestra
```

Then open the page — the H1 reads "Create Your First Hello World Flow".

Contributor guide

Open the contributing guide

Research direction

Start by tracing the generator for the `.md` endpoint, reproducing the issue with `https://kestra.io/docs/tutorial/fundamentals.md` and comparing it with the rendered page H1. Done means Markdown output uses the page’s actual H1 rather than the SEO ``, while preserving any intended SEO title in frontmatter, across the affected documentation pages.

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
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.