mdBook
mdBook copied to clipboard
rust-lang
Allow linking to sections from summary
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 #).
To have a little more context here, what would be the use case for this feature?
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.
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-headercould easily break the hierarchy. If added I think we should go with#section-headeralone 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.
@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?
My summary no longer includes any links to sections so I would not use this. Thanks for checking.
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?
Hi All,
I did an implementation for this case (the PR is already pointing to this issue), I saw in this issue some concern about this support, that I'm willing to tackle :).
First:
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.
The current implementation does not do any check, but I could definitely do checks that verify that a "link.md#anchor" is a child of the "link.md" in the Toc hierarchy if this make sense for everyone.
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.
This make sense following the previous argument, I can also add this check if this is the expected behaviour.
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.
This is already tackled in the current implementation in the PR even though it actually impact the preprocess communication format, so an outdated pre-processor will actually strip out the anchor from the Toc.
Just asking for a feedback to see fi make more sense to push forward with the checks or if anyone see any other roadblocks.
Regards
I wouldn't want to allow arbitrary links in the summary, even the proposed
page-title.md#section-headercould easily break the hierarchy. If added I think we should go with#section-headeralone and it would automatically refer to the parent chapter.
This would break compatibility with other tools such as GitBook and GitHub which both require the full path before the anchor.
We would like to see this supported, or at minimum an error thrown when trying to do this. It is quite counterintuitive to use markdown link syntax for the summary but then treat foo as a link to a file ./foo#bar.
If I'm understanding this restriction correctly, no-anchors-in-summary makes re-organizing a chapter onerous, due to the necessity of managing sections as files. That I can work with; but it also forces each section into a separate (potentially artificially small) page. I would love to be able to say this:
- [Overview](./ch-overiew.md)
- [Big Chapter](./ch-big.md)
- [Big Section in Big Chapter](#abigsection)
- [Smaller Section](#smallersection)
...and have an anchor point to e.g. ./ch-big.md#abigsection.
I suspect this would not be easy to add. Currently, it seems mdbook works on a 1:1 basis, i.e. 1 chapter : 1 file.
This mapping makes it easy to highlight the relevant TOC item based on a reverse-lookup of the filename.
To have multiple anchors mapping to different TOC items, you'd need M : 1. That means it is no longer possible to pin-point the TOC item purely based on the filename. Same situation with mapping multiple TOC items to the same file.
I got stuck with the same issue today. Ended up simply redirecting:
in SUMMARY.md:
* [Overview](1.md)
* [Framework composition](2.md)
* [Coding conventions](3.md)
* [File structure](3.1.md)
In 3.1.md:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0;url=3.html#31-file-structure">
</head>
<body>
</body>
</html>
I didn't want to create a ref in SUMMARY.md.
I wanted to create a ref in somewhere that is not SUMMARY.md to a section in a totally different markdown file.
In that case, restructuring chapters won't help.
We should be able to do this.
happy new year! has there been any consensus on how this should implemented or if it will be implemented? or workarounds?
