rust-lang / rust-lang/mdBook

When served locally, sometimes chapters load without the `.html` extension, causing 404

Open
#2,764 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

Here is my SUMMARY.md file:

# Summary

[How to use these docs](introduction.md)

# User guide

- [Getting started](getting_started.md)
- [Using Mouseless](using_mouseless.md)
- [Customizing Mouseless](customizing_mouseless.md)
- [Keybindings / command reference](keybindings.md)
- [Troubleshooting](troubleshooting.md)

# Other

- [Roadmap and Known Issues](roadmap_and_issues.md)

I triple check that the filename getting_started.md is correct, but when I run mdbook serve --open, and click the 'Getting started' link there is no .html at the end of the url in the address bar (though it appears in the preview text when I hover on the link, see screenshot), and I get a 404 page. Other pages work fine.

I've disabled [additional-js] in my .toml file, rebuilt and restarted, and still have the issue.

If I change the filename and ref (in SUMMARY.md) to a.md or a_started.md, then it works as expected.

Also, it appears to work fine once I actually deploy the files to production / live environment: https://mouseless.click/docs/

Image
Steps

No response

Possible Solution(s)

No response

Notes

No response

Version
mdbook --version
mdbook v0.4.52

(also seen on v0.4.49, before I updated)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the provided SUMMARY.md, mdBook v0.4.52, and mdbook serve --open, comparing getting_started.md with the filenames that work and with the deployed site. Done means local chapter links consistently retain the .html extension and the affected page loads without a 404.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.