People search for a Markdown syntax for a table of contents and then paste a plugin snippet into a file that will be printed. Those two jobs are different, and treating them as one is how you ship a contents page whose page numbers are already wrong.
Two different contents
A PDF is pages. A contents page in a PDF is a list of titles with the page each one starts on, printed at the front of the book, so a reader holding paper can flip to chapter four. The numbers on that list are a snapshot of the pagination at export time.
An EPUB has no pages. Its table of contents is a navigation document inside the file — the panel a Kindle or Apple Books user opens to jump. It is built from the heading outline, it updates if the headings change, and it has nothing to do with a printed list.
Get the heading outline right first
Both kinds of contents are only as good as the headings. The convention that survives contact with a typesetter, an EPUB reader and a human skimming the file:
#— the book title, once, at the top. Not a chapter.##— chapters. Every chapter, including Introduction and Conclusion if those are chapters.###— sections inside a chapter. Appear in a detailed contents; omit them from a short one.
Do not skip a level, and do not use a bigger heading because a line "should look bigger". Size is a design decision. Heading level is structure, and it is what an EPUB's navigation is made of. A book that uses # for every chapter produces a navigation panel with one entry, or with fifty, depending on how the converter guesses — either way it is wrong.
In some renderers, including bukpress, a # heading also starts a new page (except the first one). That makes # a poor choice for chapters if you already have a page-break marker for them, and a good choice for the book title sitting alone on its opening page. Use ## for chapters and put --- on the line above each one if you want them to open on a fresh sheet. Page breaks is the longer version of that.
Writing the printed contents page
For a PDF, write it. A short book does not need one — under about forty pages a reader will just turn. Above that, a single page of chapter titles, in the order they appear, is enough. You do not need leaders (the dots) and you do not need to list every ###.
## Contents
1. Why this book exists
2. The three mistakes
3. A worked example
4. What to do on Monday
---
## Why this book existsLeave the page numbers off unless you are prepared to update them after every export that changes pagination. A contents page without numbers is still useful — it is a map of the argument — and it cannot go stale. A contents page with the wrong numbers is worse than none.
If you do want the numbers, they have to come from the renderer after pagination, not from you counting. Pandoc can do this with --toc when the PDF engine supports it. Browser-print converters generally cannot, because they do not know the page a heading will land on until the print dialog has already run.
The auto-generated kind, and when to use it
| Tool | What "TOC" means | Use it for |
|---|---|---|
Pandoc --toc | A real contents page with page numbers, in LaTeX/PDF; an nav document in EPUB | Books whose pagination is stable at build time |
| VS Code / Markdown All in One | A list of links to headings, in the file itself | A README, not a book |
| GitHub, GitLab, most wikis | A sidebar of headings, generated on view | The web, not a PDF |
| EPUB export from a decent converter | The navigation document, from your ## / ### | Every ebook, always |
A list of in-file links ([Chapter 2](#chapter-2)) is the GitHub style. It works in a preview and in an EPUB; in a printed PDF those links are either dead or they jump inside a file the reader opened on paper. Do not ship them as the contents of a book you expect anyone to print.
What to include, and what to leave out
- Include numbered chapters, a preface if it is substantial, appendices.
- Leave out the title page, the copyright page, the dedication, the contents page itself.
- Leave out
###sections unless the book is a manual people will search rather than read. - Fiction often omits a contents page entirely. Chapters named "Chapter 12" in a list tell a reader nothing they could not find by turning.
A contents page is a promise about structure. If the book is a single argument in eight chapters, eight lines. If it is a reference, go deeper. Matching the depth to the way the book will be used is the whole decision.
In bukpress specifically
bukpress does not auto-generate a printed contents page, on purpose: a list with page numbers would be a snapshot, and the next edit would make it a lie. Write the contents as a ## section, put a --- after it, and it becomes a real page in the PDF.
The EPUB export — Pro — builds its navigation from the heading outline, which is the contents that actually matters on a Kindle. That is why the heading convention above is the step that is not optional. Get ## right and the ebook's table of contents appears without you making a page for it.