mdBook: Support Duplicate Entries in SUMMARY.md

So v0.4.48 just came out with #2612 and that fixed one thing and broke another.

#2612 correctly had noted that if you have a duplicate entry in SUMMARY.md that the prev/next links are broken.

However, it feels like there should still be a way to have multiple entries still. Here is how we were using it:

# Summary

[Introduction](README.md)
[Quick Start Tutorial](./GettingStarted/QuickStart.md)

---

- [Guides](./GettingStarted/README.md)
    - [Quick Start](./GettingStarted/QuickStart.md)
    - [Other Guide](./GettingStarted/AnotherGuide.md)
- [Fundamentals](./Fundamentals/README.md)

In the best scenario, the first link Quick Start Tutorial should just be a link to Guides/Quick Start and the prev/next buttons are for that page. Previously, the prev/next buttons were just for the first entry, which worked ok because both pages were considered active, and unlike in #2612 because it was nested and away from the other, it wasn’t as big of a deal.

Things tried:

  • Symlink to a separate file. This works, but has issues for devs on non-Unix. Leads to two urls, but I’m less worried about that.
  • Duplicate content. Works, but then we have to keep the two files in sync. Also leads to two urls, but I’m less worried about that.

Any other ideas on how to achieve the double pages in situations like this where it is desired?

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 2
  • Comments: 15 (9 by maintainers)

Commits related to this issue

Most upvoted comments

I need duplicate entries in SUMMARY.md too 😦

I need duplicate entries in SUMMARY.md too.

my use case

I treat SUMMARY.md as a chapters list, as follow:

- chapter 1
  - [article 1.1](1.1.md)
  - [article 1.2](1.2.md)
- chapter 2
  - [article 2.1](2.1.md)
  - [article 2.2](2.2.md)

This will cause a error, since every list item in SUMMARY.md must be a link.

So I add dummy links:

- [chapter 1](null.md)
  - [article 1.1](1.1.md)
  - [article 1.2](1.2.md)
- [chapter 2](null.md)
  - [article 2.1](2.1.md)
  - [article 2.2](2.2.md)

@jacobgkau I am sorry for the changes causing you trouble.

There are a number of fixes I can think of:

  • Make the “Previous Models” to be an unclickable “Draft page”
  • Add a a page as “Previous Models” with a link to the “Current Models”: `Full list of current and previous models
  • Split the README into two files listing the “Current models” and “Previous models” respectively with links between the two pages.
  • Create a copy of the README.md file till we have a better solution.
  • Stay on the previous version of mdbook till we provide a solution.

The ideal solution would be probably what was suggested above with the front-matter.

@ehuss it is your call, but I would not just revert that change: I’d either improve the error message to include an explanation about the problem duplicate files cause with a link to this issue or I’d change it to a warning with a link to this issue. e.g.

Having the same file twice in SUMMARY.md is causing problems in the navigation and it will be disable soon.
Please comment on this issue: https://github.com/rust-lang/mdBook/issues/2634 so we can understand
your use-case for having such duplication

It would be also nice if you commented on the solution I suggested. It could be implemented in a few hours.