SUMMARY.md

The summary file is used by mdBook to know what chapters to include, in what order they should appear, what their hierarchy is and where the source files are. Without this file, there is no book.

Even though SUMMARY.md is a markdown file, the formatting is very strict to allow for easy parsing. Let's see how you should format your SUMMARY.md file.

Structure

  1. Title It's common practice to begin with a title, generally # Summary. But it is not mandatory, the parser just ignores it. So you can too if you feel like it.

  2. Prefix Chapter Before the main numbered chapters you can add a couple of elements that will not be numbered. This is useful for forewords, introductions, etc. There are however some constraints. You can not nest prefix chapters, they should all be on the root level. And you can not add prefix chapters once you have added numbered chapters.

    [Title of prefix element](relative/path/to/markdown.md)
    
  3. Part Title: Headers can be used as a title for the following numbered chapters. This can be used to logically separate different sections of book. The title is rendered as unclickable text. Titles are optional, and the numbered chapters can be broken into as many parts as desired.

  4. Numbered Chapter Numbered chapters are the main content of the book, they will be numbered and can be nested, resulting in a nice hierarchy (chapters, sub-chapters, etc.)

    # Title of Part
    
    - [Title of the Chapter](relative/path/to/markdown.md)
    
    # Title of Another Part
    
    - [More Chapters](relative/path/to/markdown2.md)
    

    You can either use - or * to indicate a numbered chapter.

  5. Suffix Chapter After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.

All other elements are unsupported and will be ignored at best or result in an error.

Other elements

  • Separators In between chapters you can add a separator. In the HTML renderer this will result in a line being rendered in the table of contents. A separator is a line containing exclusively dashes and at least three of them: ---.
  • Draft chapters Draft chapters are chapters without a file and thus content. The purpose of a draft chapter is to signal future chapters still to be written. Or when still laying out the structure of the book to avoid creating the files while you are still changing the structure of the book a lot. Draft chapters will be rendered in the HTML renderer as disabled links in the table of contents, as you can see for the next chapter in the table of contents on the left. Draft chapters are written like normal chapters but without writing the path to the file
    - [Draft chapter]()