rust-lang/mdBook · error

Suffix chapters cannot be followed by a list

Error message

Suffix chapters cannot be followed by a list

What it means

SUMMARY.md structure must be: optional prefix chapters, then the numbered list, then optional suffix (affix) chapters. parse_affix handles the tail; if, while parsing suffix chapters, it encounters a new list start after suffix links have begun, the document is malformed and the parser raises this error.

Source

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

            if is_prefix { "prefix" } else { "suffix" }
        );

        loop {
            match self.next_event() {
                Some(ev @ Event::Start(Tag::List(..)))
                | Some(
                    ev @ Event::Start(Tag::Heading {
                        level: HeadingLevel::H1,
                        ..
                    }),
                ) => {
                    if is_prefix {
                        // we've finished prefix chapters and are at the start
                        // of the numbered section.
                        self.back(ev);
                        break;
                    } else {
                        bail!(self.parse_error("Suffix chapters cannot be followed by a list"));
                    }
                }
                Some(Event::Start(Tag::Link { dest_url, .. })) => {
                    let link = self.parse_link(dest_url.to_string());
                    items.push(SummaryItem::Link(link));
                }
                Some(Event::Rule) => items.push(SummaryItem::Separator),
                Some(_) => {}
                None => break,
            }
        }

        Ok(items)
    }

    fn parse_parts(&mut self) -> Result<Vec<SummaryItem>> {
        let mut parts = vec![];

View on GitHub (pinned to dc21064fc2)

Solutions

1. Move the stray list's chapters into the single numbered list or the prefix section of SUMMARY.md.
2. Convert the suffix links into part of the main numbered list if they should be numbered.
3. Remove the second list entirely; mdBook supports only prefix chapters, one numbered list, then suffix chapters.

Example fix

<!-- before: SUMMARY.md -->
- [Suffix](suffix.md)

# Summary

- [Chapter 1](ch1.md)
- [Other](other.md)

<!-- after -->
# Summary

- [Chapter 1](ch1.md)
- [Other](other.md)

- [Suffix](suffix.md)

// Reject SUMMARY.md with suffix links followed by another list
const lines = summary.split('\n');
let seenNumbered = false, seenSuffix = false;
for (const line of lines) {
  if (/^- \[/.test(line) && seenNumbered && !/^\s{2,}/.test(line)) seenSuffix = true;
  else if (/^-\s|^[0-9]+\./.test(line) && seenSuffix) throw new Error('list after suffix chapters');
  else if (/^[0-9]+\. \[/.test(line)) seenNumbered = true;
}

When it happens

Trigger: In SUMMARY.md, after the numbered list, one or more standalone suffix chapter links appear, followed by another Markdown list (e.g. a second numbered list or bullet list) — an Event::List arrives while is_prefix is false.

Common situations: Writing two numbered sections separated by suffix links; accidentally indenting later chapters so they form a new list; legacy SUMMARY layouts mixing affix chapters between lists.

Related errors

• Duplicate file in SUMMARY.md: {:?}
• The link items for nested chapters must only contain a hyper
• failed to parse SUMMARY.md line {}, column {}: {}
• Unable to get last link because the list of SummaryItems doe
• 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/23d4c70ae1bef981. Report an issue: GitHub.