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 https://github.com/rust-lang/mdBook/issues/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 https://github.com/rust-lang/mdBook/pull/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.

[Leroy-X]

I need duplicate entries in SUMMARY.md too :(

[0x4ndy]

I've just upgraded to the latest version of mdbook, and I was surprised to see this error. Is there any reason why the duplicate entries in the SUMMARY.md file are not allowed?

[EDIT] I've read through #2612. A more sensible solution would be to avoid generating the same file twice, instead of preventing duplicates altogether.

[szabgab]

@0x4ndy What is your use-case for having the same entry and thus the same content twice?

[0x4ndy]

@szabgab I don't want to have the content twice. What I would like is to have multiple links to the same content in the summary. For instance, something like this:

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

So that if I click on [chapter 1], the 1.1.md will be loaded. I understand that the intention of #2612 was to avoid duplication in file generation, but because of it, now we have to duplicate and generate files manually to workaround this fix.

[simonmichael]

Another possible use case: my sidebar used to start with a short list of the most notable pages. Below that I had a full alphabetic list of all site content. Both the short list and the exhaustive list were useful ways to find things. But now, a page can be linked in only one or the other.

[snaeil]

@szabgab I don't want to have the content twice. What I would like is to have multiple links to the same content in the summary. For instance, something like this:

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

So that if I click on [chapter 1], the 1.1.md will be loaded. I understand that the intention of #2612 was to avoid duplication in file generation, but because of it, now we have to duplicate and generate files manually to workaround this fix.

I have the same use case too and I have seen a lot of documentations with this approach.

[szabgab]

The main problem with duplicate entries wasn't that it created the file twice, but that the next/prev navigation was broken. In the example @0x4ndy gave it is less of an issue as the duplicated page(s) are one after the other immediately. (as opposed to two totally separated places) So maybe that should be allowed, but maybe we should have some other way to express this intention so duplication of a pages won't happen by mistake.

[0x4ndy]

Well, perhaps in my use case, maybe the better approach would be to have a possibility to customize the content of the SUMMARY.md in a way that we could put anything we would like in the form of HTML/CSS/JS, just like we can do with the other parts of the UI. I don't know if that's possible right now.

[shenef]

Is anyone actually using the previous/next buttons or left/right arrow keys to navigate between chapters? I've only gotten complaints about them hurting the user experience because they cause accidental navigation away from the current page so I usually remove that functionality. I can see how someone would use it with an actual novel - but mdBook seems to be used mostly for documentation and nobody reads that linearly.

[szabgab]

I use the buttons a lot and even plan to add hotkeys to them when I get a round tuit.

[your-diary]

I do need duplicate entries and this issue prevents me from updating the mdbook version.

My dev team uses mdbook as an internal documentation and we have a shortcut section in which frequently accessed pages are listed.

The SUMMARY.md we have is like this:

This has been easily maintainable for years because adding to or removing from the shortcut section only requires us to edit a few lines of SUMMARY.md.

[SverreArntsen]

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 Quick Start Tutorial

---

• Guides
  • Quick Start
  • Other Guide
• Fundamentals 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.

oh, this feature wold help us a lot if/when implemented. like, A LOT :-) just sayin'