actions
/
mdBook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1534 from joshrotenberg/docs/guide-summary-updates 

Guide updates: summary.md
This commit is contained in:
Eric Huss 2021-05-17 14:38:18 -07:00 committed by GitHub
parent 0f0dce8d6c d147a85006
commit 1411ea967a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 73 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
guide/src/format/summary.md
View File

@ -4,66 +4,96 @@ 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 order they should appear, what their hierarchy is and where the source files
are. Without this file, there is no book. are. Without this file, there is no book.
Even though `SUMMARY.md` is a markdown file, the formatting is very strict to This markdown file must be named `SUMMARY.md`. Its formatting
allow for easy parsing. Let's see how you should format your `SUMMARY.md` file. is very strict and must follow the structure outlined below to allow for easy
parsing. Any element not specified below, be it formatting or textual, is likely
to be ignored at best, or may cause an error when attempting to build the book.
#### Structure ### Structure
1. ***Title*** It's common practice to begin with a title, generally <code 1. ***Title*** - While optional, it's common practice to begin with a title, generally <code
class="language-markdown"># Summary</code>. But it is not mandatory, the class="language-markdown"># Summary</code>. This is ignored by the parser however, and
parser just ignores it. So you can too if you feel like it. can be ommitted.
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.
```markdown ```markdown
[Title of prefix element](relative/path/to/markdown.md) # Summary
``` ```
3. ***Part Title:*** Headers can be used as a title for the following numbered 1. ***Prefix Chapter*** - Before the main numbered chapters, prefix chapters can be added
that will not be numbered. This is useful for forewords,
introductions, etc. There are, however, some constraints. Prefix chapters cannot be
nested; they should all be on the root level. And you can not add
prefix chapters once you have added numbered chapters.
```markdown
[A Prefix Chapter](relative/path/to/markdown.md)
- [First Chapter](relative/path/to/markdown2.md)
```
1. ***Part Title*** - Headers can be used as a title for the following numbered
chapters. This can be used to logically separate different sections chapters. This can be used to logically separate different sections
of book. The title is rendered as unclickable text. of the book. The title is rendered as unclickable text.
Titles are optional, and the numbered chapters can be broken into as many Titles are optional, and the numbered chapters can be broken into as many
parts as desired. parts as desired.
```markdown
# My Part Tile
4. ***Numbered Chapter*** Numbered chapters are the main content of the book, - [First Chapter](relative/path/to/markdown.md)
they will be numbered and can be nested, resulting in a nice hierarchy ```
(chapters, sub-chapters, etc.)
1. ***Numbered Chapter*** - Numbered chapters outline the main content of the book
and can be nested, resulting in a nice hierarchy
(chapters, sub-chapters, etc.).
```markdown ```markdown
# Title of Part # Title of Part
- [Title of the first Chapter](relative/path/to/markdown.md) - [First Chapter](relative/path/to/markdown.md)
- [Title of the second Chapter](relative/path/to/markdown2.md) - [Second Chapter](relative/path/to/markdown2.md)
- [Title of a sub Chapter](relative/path/to/markdown3.md) - [Sub Chapter](relative/path/to/markdown3.md)
# Title of Another Part # Title of Another Part
- [More Chapters](relative/path/to/markdown4.md) - [Another Chapter](relative/path/to/markdown4.md)
``` ```
You can either use `-` or `*` to indicate a numbered chapter. Numbered chapters can be denoted with either `-` or `*`.
5. ***Suffix Chapter*** After the numbered chapters you can add a couple of 1. ***Suffix Chapter*** - Like prefix chapters, suffix chapters are unnumbered, but they come after
non-numbered chapters. They are the same as prefix chapters but come after numbered chapters.
the numbered chapters instead of before. ```markdown
- [Last Chapter](relative/path/to/markdown.md)
All other elements are unsupported and will be ignored at best or result in an [Title of Suffix Chapter](relative/path/to/markdown2.md)
error. ```
#### Other elements 1. ***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.
```markdown
- [Draft Chapter]()
```
- ***Separators*** In between chapters you can add a separator. In the HTML renderer 1. ***Separators*** - Separators can be added before, in between, and after any other element. They result
this will result in a line being rendered in the table of contents. A separator is in an HTML rendered line in the built table of contents. A separator is
a line containing exclusively dashes and at least three of them: `---`. a line containing exclusively dashes and at least three of them: `---`.
- ***Draft chapters*** Draft chapters are chapters without a file and thus content. ```markdown
The purpose of a draft chapter is to signal future chapters still to be written. # My Part Title
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. [A Prefix Chapter](relative/path/to/markdown.md)
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
```markdown - [First Chapter](relative/path/to/markdown2.md)
- [Draft chapter]() ```
```
### Example
Below is the markdown source for the `SUMMARY.md` for this guide, with the resulting table
of contents as rendered to the left.
```markdown
{{#include ../SUMMARY.md}}
```