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