rust-lang/mdBook · error

The link items for nested chapters must only contain a hyper

Error message

The link items for nested chapters must only contain a hyperlink

What it means

Nested chapters in SUMMARY.md are written as a link whose item is a nested list. parse_nested_item expects the first event of a nested item to be the start of a hyperlink; if it sees any other event (paragraph text, list item with extra content, etc.), it warns and raises this error because nested items must contain only a hyperlink.

Source

Thrown at crates/mdbook-summary/src/lib.rs:558

                    let mut number = parent.clone();
                    number.push(num_existing_items as u32 + 1);
                    trace!(
                        "Found chapter: {} {} ({})",
                        number,
                        link.name,
                        link.location
                            .as_ref()
                            .map(|p| p.to_str().unwrap_or(""))
                            .unwrap_or("[draft]")
                    );

                    link.number = Some(number);

                    return Ok(SummaryItem::Link(link));
                }
                other => {
                    warn!("Expected a start of a link, actually got {:?}", other);
                    bail!(self.parse_error(
                        "The link items for nested chapters must only contain a hyperlink"
                    ));
                }
            }
        }
    }

    fn parse_error<D: Display>(&self, msg: D) -> Error {
        let (line, col) = self.current_location();
        anyhow::anyhow!(
            "failed to parse SUMMARY.md line {}, column {}: {}",
            line,
            col,
            msg
        )
    }

    /// Try to parse the title line.

View on GitHub (pinned to dc21064fc2)

Solutions

1. Make each nested list item contain exactly one hyperlink, e.g. " - [Child](child.md)".
2. Remove any text, formatting, or HTML that follows the parent link or appears inside nested items.
3. Regenerate SUMMARY.md with `mdbook build`'s create/scaffold output as a template for correct nesting.

Example fix

<!-- before: SUMMARY.md -->
- [Parent](parent.md) — advanced topics
  - [Child](child.md)

<!-- after -->
- [Parent](parent.md)
  - [Child](child.md)

// Ensure nested list items contain only a link
for (const line of summary.split('\n')) {
  if (/^\s+-\s/.test(line) && !/^\s+-\s\[[^\]]+\]\([^)]+\)\s*$/.test(line)) {
    throw new Error(`nested item must be only a link: ${line}`);
  }
}

When it happens

Trigger: Writing nested chapter entries in SUMMARY.md where a nested list item contains more than a bare link — e.g. "- [Parent](parent.md) some text" followed by an indented list, or a nested item with emphasis/inline HTML instead of a plain link.

Common situations: Adding descriptive text after a parent link expecting it to be ignored; accidentally inserting characters or formatting inside nested list items; hand-generating SUMMARY.md with scripts that emit extra markup.

Related errors

• Unable to get last link because the list of SummaryItems doe
• Duplicate file in SUMMARY.md: {:?}
• Suffix chapters cannot be followed by a list
• failed to parse SUMMARY.md line {}, column {}: {}
• redirect entry for `{original}` only has source paths with `

AI-assisted analysis of rust-lang/mdBook@dc21064fc2 (2026-09-01). Data as JSON: /api/errors/f2830f69618c3423. Report an issue: GitHub.