Weird behavior on outline (README.md) makes content 404

[mattaereal]

mdBook Relative Path Navigation Issue (v0.4.41+)

Problem Description

When using mdBook version 0.4.41 or higher, clicking on any link in the sidebar causes all subsequent sidebar links to have incorrect relative paths appended to them, resulting in 404 errors.

Steps to Reproduce

1. Build a book with mdBook v0.4.41 or higher where chapters are organized in subdirectories
2. Navigate to the book's index page
3. Click on any sidebar link that points to a page in a subdirectory (e.g., /awareness/index.html)
4. Observe that all other sidebar links now have the subdirectory path appended (e.g., all links become ./awareness/...)

Example

• Initial state: All sidebar links work correctly
• Click on: https://example.com/awareness/index.html
• Result: All sidebar links are now broken:
  • ./intro/introduction.html becomes ./awareness/intro/introduction.html (404)
  • ./wallet-security/index.html becomes ./awareness/wallet-security/index.html (404)

Root Cause

The issue was introduced in mdBook v0.4.41 with PR #2414, which changed how the sidebar is loaded. The sidebar is now loaded from a separate JavaScript file to reduce file size, but this change broke relative path handling when navigating between pages in different subdirectories.

Technical Details

• Affected versions: mdBook v0.4.41 and higher
• Not affected: mdBook v0.4.40 and lower
• Related issues:
  • Index page of the book can have broken relative links when in a subdirectory rust-lang/mdBook#2341 (Index page broken relative links in subdirectories)
  • Broken relative links when using first chapter as an index page. rust-lang/mdBook#2060 (Broken relative links when using first chapter as index)
  • site-url not respected in links rust-lang/mdBook#1764 (site-url not respected in links)

Current Workaround

We've reverted to using mdBook v0.4.40, which does not have this issue. This is a stable version without known security vulnerabilities (the last mdBook CVE was fixed in v0.4.5).

Implementation

In our vercel_build.sh:

# Download and extract mdBook
echo "Downloading mdBook v0.4.40..."
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin

Attempted Solutions That Did Not Work

1. Creating an index.md file - While this addresses some mdBook issues with first chapter as index, it doesn't fix the sidebar path problem
2. Setting site-url = "/" in book.toml - The site-url configuration doesn't rewrite markdown links as expected
3. Updating custom theme files - The issue is in mdBook's core sidebar loading mechanism

Environment

• mdBook versions tested: v0.4.40 (works), v0.4.41-v0.4.52 (broken)
• Deployment: Vercel
• Book structure: Multiple chapters organized in subdirectories
• Theme: Custom theme with mdbook-admonish and other plugins

[the-caliber]

Just sharing one thing i noticed, not sure if this is worth sharing,
Ignore this if it's already covered or expected behavior of mdbook.

When we check any vercel deployment preview, E.g in the case of #182 clicking on lets say Fuzz testing in index (left pane) two times creates path confusion (redirects to incorrect path) result of which it shows Document not found (404) page.

Same issue does not exist on .dev or .org as far as i could check.

Wondering if it can create any future problems for .dev or .org.

[mattaereal]

It is exactly because of this! That's why I'm keeping v0.4.40 for now :)