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

@dtolnay

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

This would break compatibility with other tools such as GitBook and GitHub which both require the full path before the anchor.

add support for links with anchors from summary, issue rust-lang#167

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?

fix page rendering

Any updates or any workaround?

fix page rendering

@lapk-arista out here doing gods work

Reverting SUMMARY.md changs

So, 2025 is the year?

@ehuss

Hi @ehuss, I am interesting in figuring out and adding this feature to mdbook if that would be ok. Can you please assign this to me?

I could really use this! Please make it happen!

I needed this, so I made a rather hacky script called "build-book" that creates a table of contents (TOC.md) from SUMMARY.md before calling the normal build command. It:

Reads each line in SUMMARY.md and makes the corresponding TOC entry for that file.
Then reads the file that summary line points to, finds sub-sections in there and adds them to the table of contents.
Repeat.

Note: I included sub-sections up to depth 3. Some users will a different cut-off.

The script is quite specific to my structure so I'm not sure sharing it will help more than hinder, but if you're desperate for a solution, something like this can be put together in 10 minutes. Still, if someone has a couple of days to make a nice solution that covers edge cases, that would still be appreciated by many, I'm sure. 🙂

Also, I'm interested in the table of contents for PDF versions of the document, so I'm not overly bothered by whether subsections appear in a browser navigation pane.

Fix various broken links in docs.

Fix various broken links in docs. (#12125)

This works for me in mdbook v0.4.52.

<!-- file_1.md -->
# First Title

## SECOND TITLE

<!-- file_2.md -->

[Link to first](file_1.md#first-title)

[Second](file_1.md#second-title)

Navigation Menu

Repository navigation

Allow linking to sections from summary #167

10 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow linking to sections from summary #167

Description

Activity

azerupi commented on Aug 28, 2016

dtolnay commented on Aug 28, 2016

azerupi commented on Aug 28, 2016

Michael-F-Bryan commented on Jan 2, 2018

dtolnay commented on Jan 2, 2018

buschtoens commented on Dec 23, 2019

tglman commented on Mar 9, 2020

mcarton commented on Mar 24, 2020

10 remaining items

nejdetckenobi commented on Dec 2, 2022

Lana-chan commented on Feb 17, 2023

lubingtan commented on Aug 23, 2023

deoidh commented on Sep 3, 2024

Volscente commented on Jan 10, 2025

spperforce commented on Jan 28, 2025

peternoyes commented on Aug 23, 2025

bitdivine commented on Nov 9, 2025

alex-sc-kao commented on May 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions