Skip to content

fix(html): correct relative link depth on default-module subpages#808

Open
crowlbot wants to merge 2 commits into
mainfrom
fix-default-module-subpage-links
Open

fix(html): correct relative link depth on default-module subpages#808
crowlbot wants to merge 2 commits into
mainfrom
fix-default-module-subpage-links

Conversation

@crowlbot

@crowlbot crowlbot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

Problem

When HTML docs are generated for a package with multiple entrypoints, the pages for symbols belonging to the default/main module contain broken relative links: stylesheets fail to load, search-result links 404, and cross-links lose the base path. See #717 and #685.

For example, a symbol page rendered for the main module links back to the root with ../ when it actually needs ../../, so links like ~/Foo.html resolve to /~/Foo.html (missing a path segment) and 404.

Cause

Symbol pages are always written to {short_path.path}/~/{name}.html, for every module including the main entrypoint (src/html/mod.rs). But href_path_resolve hard-coded the main entrypoint to a directory depth of 1 when computing the ../ prefix:

UrlResolveKind::Symbol { file, .. } => "../".repeat(if file.is_main {
  1
} else {
  file.path.split('/').count() + 1
}),

That is only correct when the main module's path is . (the common single-package case, where the page lives at ./~/Foo.html). When several entrypoints share a common ancestor, the main module gets a real path such as index.ts, so its symbol pages live at index.ts/~/Foo.html — two directories deep — but were still linked back to the root with a single ../. This also explains why #685 saw the bug depend on entrypoint ordering: it changes which module becomes the default and what path it gets.

Fix

Compute the depth from the actual number of segments in file.path, treating . as zero segments (it adds no directory). This unifies the main and non-main cases:

  • main module at . → symbol page ./~/Foo.html../ (unchanged)
  • main module at index.ts → symbol page index.ts/~/Foo.html../../ (fixed)
  • non-main module at foofoo/~/Bar.html../../ (unchanged)

Added unit tests in src/html/util.rs pinning all three cases; the full html_test snapshot suite is unaffected.

Fixes #717

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

crowlbot added 2 commits June 9, 2026 15:50
Symbol pages are written to `{short_path.path}/~/{name}.html` for every
module, including the main entrypoint. But `href_path_resolve` hard-coded
the main entrypoint to a directory depth of 1 when computing the `../`
prefix for links back to the root.

That is only correct when the main module's path is `.` (the usual
single-package case). When several entrypoints share a common ancestor,
the main module gets a deeper path (e.g. `index.ts`), so its symbol pages
live two directories deep yet linked back to the root with a single
`../` — producing 404s for stylesheets, search results and cross-links on
those subpages.

Compute the depth from the actual number of path segments instead,
treating `.` as zero segments so the common case is unchanged.
@crowlbot crowlbot force-pushed the fix-default-module-subpage-links branch from 2df8d67 to ba0f8b0 Compare June 9, 2026 16:03
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.

Deno doc inserts incorrect links in html

2 participants