Allow linking to sections from summary

[dtolnay]

In SUMMARY.md I have a link to a section like [Section header](page-title.md#section-header). This works in GitBook but mdBook creates empty files page-title.md#section-header and book/page-title.md#section-header (file names containing #).

[azerupi]

To have a little more context here, what would be the use case for this feature?

[dtolnay]

Sections A and B for which both of the following are true:

• I want A and B on the same page because users will want to have both visible at once, cross-referencing between them.
• A large percentage of visitors to my site are looking specifically for sections A and B so I want to provide links directly to them in a predictable place.

[azerupi]

I assume this requirement is for the Serde book? Particularly, here is where it is used currently.

I do see the appeal for such a feature, but there are some drawbacks too.

• I wouldn't want to allow arbitrary links in the summary, even the proposed page-title.md#section-header could easily break the hierarchy. If added I think we should go with #section-header alone and it would automatically refer to the parent chapter.
• There are some edge cases the parser would have to worry about. For example: Section links can't contain sub-chapters, they also can't be at the root level.
• The current implementation assumes all links from the summary are files. We could add some dirty checks to make it work, but if we want to do it properly, the concerned parts should be rewritten to support it.

Getting this right seems to be more complicated than it might appear. When you scroll to the sub-section the sidebar has to update the current chapter (= blue highlight) and the url should be updated accordingly to allow for easy linking. Gitbook handles this well. But this feature seems to break the keyboard navigation in Gitbook.

[Michael-F-Bryan]

@dtolnay, I believe you're using GitBook for serde.rs at the moment, would you still say this is something you'd like to see in mdbook?

[dtolnay]

My summary no longer includes any links to sections so I would not use this. Thanks for checking.

[buschtoens]

I'm still very interested in this feature! At the very least, I would recommend to throw an error with a link to this issue when trying to build a SUMMARY.md that has #anchors.

I have very little Rust experience so far (front end dev primarily), but can I potentially help with this? Would this feature be appreciated / accepted to begin with?