Support Duplicate Entries in SUMMARY.md

[wilwade]

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?

[szabgab]

Thanks for reporting and sorry for breaking your book. Is it a public book? Is it already listed on public mdbooks?

Maybe we need to be able to create a file the states where its source can be found, where to copy its content from.

# Summary

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

---

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

The src/QuickStart.md would contain:

copy: ./GettingStarted/QuickStart.md

or better yet

---
copy: ./GettingStarted/QuickStart.md
---

(For this we need to introduce the front-matter that was also mentioned here #2142 and that I very much would like to implement)

Then the resulting site would have the same content twice. Both in GettingStarted/QuickStart.html and in QuickStart.html. Both could have its right-left navigation correctly and QuickStart.html would have

<link rel="canonical" href="GettingStarted/QuickStart.html" />

The copy should be automatically excluded from the indexing.

[wilwade]

Is it a public book

It is: https://github.com/ProjectLibertyLabs/gateway/tree/main/docs (just updated to remove the double link for now)
Deployed: https://projectlibertylabs.github.io/gateway/

Maybe we need to be able to create a file the states where its source can be found, where to copy its content from.

Either of those versions would work for all of our needs I can think of.

Another option might be to allow for other links in the SUMMARY. I know there are some issues around that sort of thing already such as #2573

P.S. Thanks so much for helping build such a great tool!

[szabgab]

@wilwade You might want to go back to use the previous version of mdbook that still allowed the duplicate files till we figure out and implement a better way to have that.

Nice book, I've added it to the list of public sites.

I think the format of SUMMARY.md needs a lot more work as there are several open issues regarding it. I would not want to add some patch on it to support duplicate files just to realize later that it interferes with other requests.

[wilwade]

@szabgab Thanks that all makes sense to me! Thanks for keeping this in mind and feel free to post ideas if you want any feedback.

We're considering about a bit of release code or part of the custom theme that duplicates the page or such still. Fortunately, it is isn't a blocking issue. I've done some fairly heavy theme modifications in on a related mdbook so, fairly comfortable with hacking something in there if we need to. https://docs.frequency.xyz/ (GitHub: https://github.com/frequency-chain/docs)

[smilingpoplar]

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)

[szabgab]

@smilingpoplar Thanks for your input. Do you have any content in the null.md file? Do you do anything about the fact that left and right arrows are "broken" on for every chapter page except one?
And yes, this limitation of mdbook you point at bothers me too.

Finally, is the source of your book public?

[smilingpoplar]

@smilingpoplar Thanks for your input. Do you have any content in the null.md file? Do you do anything about the fact that left and right arrows are "broken" on for every chapter page except one? And yes, this limitation of mdbook you point at bothers me too.

Finally, is the source of your book public?

null.md is just an empty file to bypass restriction.

I use mdbook to organize my personal knowledge base, so it's ok to have some "broken" link.

[szabgab]

@smilingpoplar ok, so for the short run you can either stay with the previous version of mdbook that still allowed duplicate entries or you can create a separate filename for each chapter (null1.md etc.).

On the longer run we might need to offer a way where we can have chapter heads without associated files.

[szabgab]

@smilingpoplar have you tried using draft chapters?:

- [chapter 1]()

They might provide what you intend to achieve.

[smilingpoplar]

@smilingpoplar have you tried using draft chapters?:

Oh, it works. Thanks.

[jacobgkau]

We have duplicate entries in the System76 Tech Docs mdbook as well: https://tech-docs.system76.com/

We have the README.md "home page" that links to all of our chapters. However, those chapters are split into two categories (current models and previous models). We want that grouping to appear in the sidebar, so currently, we're got two links (for those groups) both pointing to README.md.

From what I understand, we'll either need to use draft chapters (making the section headers in the sidebar non-clickable), or make a structural change splitting out our current and previous models into different pages so they can be linked as different files?

Edit: Just to note, I understand the concern with the next/previous button behavior-- when just navigating through with the next button, we cycle through all of our current models and never get to the previous models, which I would consider a bug. However, people usually come to this particular docs website to access a specific chapter, not to browse the entire book/website in a linear fashion.

[ehuss]

@szabgab It sounds like this is affecting quite a number of users. Would you be ok with reverting #2613 until we figure out a different solution?

[szabgab]

@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.

[snaeil]

I am having the same problem with a private deployment and using "draft chapters" as described above works for me as a temporary solution.