Skip to content

fix: rewrite relative links between docs pages - #40

Merged
barredterra merged 4 commits into
version-16-hotfixfrom
fix-relative-page-links
Oct 29, 2026
Merged

barredterra merged 4 commits into
version-16-hotfixfrom
fix-relative-page-links

Conversation

@barredterra

Copy link
Copy Markdown
Member

Closes #6

Problem

A Markdown link to a sibling page, such as [Setup](setup.md), rendered as a literal href="setup.md". The link did not resolve against the docs route. Also, the bundled docs linked to /app/docs/en/..., so every reader got the English page.

Changes

  • rewrite_page_links() changes relative <a href="….md"> links into the locale-neutral route /desk/docs/<path>. The docs browser then opens the page in the reader's language.
    • It resolves the link against the folder of the current page. A page from an index.md file is its own folder. The #fragment stays on the link.
    • A page written in Desk has no file. It counts as a folder index when other pages exist below its path. Because of this, a Desk override of guides/index.md keeps its relative links.
    • These links stay unchanged: absolute URLs, links that start with /, mailto:, #anchor, links to other file types, links with a ?query, and links that go above the docs root.
  • The bundled cross-links (en and de) now use /desk/docs/<path> without a locale.
  • The authoring guide (en and de) has a new "Links between pages" section.

Tests

There are 3 new tests in compendium/tests/test_docs.py:

  • relative links from index pages and normal pages, including ./, ../, index.md, #fragment and a German translation
  • a Desk override of a folder index
  • links that must stay unchanged

Notes

  • The child-page list in build_overview_payload still links to /app/docs/{locale}/.... This PR does not change it.
  • A link to the root index.md becomes /desk/docs. The docs browser then opens the first page.

Markdown links like [Setup](setup.md) rendered as a literal href that did
not resolve. Relative links to .md files now point to the locale-neutral
docs route, so each reader gets the page in their own language.

Also drop the hard-coded locale from the bundled cross-links and document
how to link between pages in the authoring guide.

Closes #6
@greptile-apps

greptile-apps Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no blocking issues remain.

Reviews (2) · Last reviewed commit: "fix: decode HTML entities in page links" · Reviewed by Greptile

Comment thread compendium/docs.py Resolved
Comment thread compendium/docs.py Resolved
Comment thread compendium/docs.py Resolved
@barredterra

Copy link
Copy Markdown
Member Author

@greptileai

@barredterra

Copy link
Copy Markdown
Member Author

@Mergifyio backport version-15-hotfix

@mergify

mergify Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

backport version-15-hotfix

✅ Backports have been created

Details

@barredterra
barredterra merged commit 7222dda into version-16-hotfix Oct 29, 2026
4 checks passed
@barredterra
barredterra deleted the fix-relative-page-links branch October 29, 2026 14:25
barredterra added a commit that referenced this pull request Oct 29, 2026
Co-authored-by: Raffael Meyer <14891507+barredterra@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Relative links between pages are not rewritten

1 participant