Book Parts

Parts can only be used when the document type is book. The presence of at least one part implies that the document is a multi-part book. (There’s no dedicated doctype for a multi-part book to distinguish it from a book with only chapters).

Anatomy of a part

A part is a level 0 section. A part must contain at least one level 1 section. The first part is the first level 0 section in the document that comes after the document title. Like the document title, a part is designated by a level 0 section title (=).

= Book Title
:doctype: book

= Part I

...

A part can have an optional introduction (similar to the preamble of the document), known as a part intro. The part intro is the content between the part title and the first section in the part. The part intro can be marked explicitly using the partintro style on either a paragraph or open block.

AsciiDoc provides document attributes to control the numbering and labeling parts.

Part intro

The content between the part title and the first section in the part is the part intro. Normally, the part intro is inferred, as shown here:

= Book Title
:doctype: book

= Part I

This is the implicit partintro.

== Chapter A

You can mark the part intro explicitly by adding the partintro style on the sole block before the first section.

= Book Title
:doctype: book

= Part I

[partintro]
This is the implicit partintro.

== Chapter A

Special sections for parts

A part can have its own preface, bibliography, glossary and index.

= Multi-Part Book with Parts that Have Special Sections
Author Name <author@example.com>
:doctype: book

[preface]
= Book Preface

This is the preface for the whole book.

=== Preface Subsection

Chinchillas rule the world.

= Part 1

This is the introduction to the first part of our mud-encrusted journey.

== Chapter 1

There was mud...

== Chapter 2

Great gobs of mud...

[glossary]
== Part 1 Glossary

[glossary]
mud:: wet, cold dirt

= Part 2

[preface]
== Part 2 Preface

This is a preface just for part 2.

== Chapter 3

The mud had turned to cement...

Special sections as part siblings

In a multipart book, parts occupy the top level of the hierarchy. If you define a special section at level 1 that follows the parts in a multipart book, it will become a child of the last part. If, instead, you want the special section to be a sibling, it has to be part-like, meaning it must be defined as as a level 0 section. To be consistent, it’s best to do the same for special sections that come before parts, though technically the syntax doesn’t require it.

The AsciiDoc syntax allows special sections in a multipart book to be defined using a level 0 section title (i.e., =). When the document is parsed, these sections still end up as level 1 sections. Despite this level change, they remain siblings of parts in the hierarchy. If the special section supports nested sections, the next level must be level 2 (i.e., ===), since the special section itself has level 1.

Here’s an example of a multi-part book that has a special section before and after the part.

= Multi-Part Book with Special Sections
Author Name <author@example.com>
:doctype: book
:toc:

[colophon]
= The Colophon

Text at the beginning of a book describing facts about its production.

= The First Part

== The First Chapter

Chapters can be grouped by preceeding them with a level 0 Book Part title.

[appendix]
= The Appendix

=== Basics

A multipart book can have appendixes, which should be defined at section level 0.

=== Subsections

Subsections of an appendix in a multipart book should start at level 2.

When you convert this document, notice that the special sections are siblings of the part in the table of contents.

TOC of multipart book with special sections