Docs: relative Markdown link cause 404 on GitHub Pages

[Romulad]

• cli-testing-library version: 3.0.1
• Testing Framework and version: N/A (Docs-only issue)
• DOM Environment: GitHub Pages deployment

Relevant code or config:

[API reference for `render` and friends](./api)

What you did:

While navigating the documentation website at https://cli-testing.com. I browsed subpages and clicked on internal links like [API reference forrender and friends](./api.md).

What happened:

Links that use relative paths (./some-page) break.
For example, when on https://cli-testing.com/guides/introduction/, clicking a link like ./api leads to https://cli-testing.com/guides/introduction/api instead of https://cli-testing.com/guides/api/, causing a 404 error.

Reproduction:

Click on Get started:

Then click a link in Further Reading section:

You will have this:

4. ✅ This behavior does not happen when deploying to platforms like Render onrender.com

Problem description:

The use of relative paths (./file) in Markdown files causes unexpected behavior only on certain hosting platforms, particularly GitHub Pages. The browser interprets them relative to the current URL, which breaks when not on the root.

This causes some internal documentation links to return 404 errors when the site is deployed on GitHub Pages. On other platforms like Render, the issue doesn’t appear due to different URL resolution behavior.

Suggested solution:

One way to fix this can be:

• In Markdown files, use <a> tags with metadata:

  <a href="./api.md" data-astro-link="/guides/api">Api</a>

• Then, during the Astro build, use a rehype plugin to:
  • Replace href with the value of data-astro-link for website output
  • Leave original href for GitHub or MD readers

Happy to contribute the implementation if this direction is accepted.