use crate::tests::prelude::*;
track_file!("ref/asciidoc-lang/docs/modules/sections/pages/parts.adoc");
non_normative!(
r#"
= 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 (`=`).
----
include::example$part.adoc[tag=basic]
...
----
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 xref:part-numbers-and-labels.adoc[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:
-----
include::example$part.adoc[tags=**;!style]
-----
You can mark the part intro explicitly by adding the `partintro` style on the sole block before the first section.
-----
include::example$part.adoc[tags=**]
-----
== Special sections for parts
A part can have its own xref:preface.adoc[preface], xref:bibliography.adoc[bibliography], xref:glossary.adoc[glossary] and xref:user-index.adoc[index].
----
include::example$part-with-special-sections.adoc[]
----
Special sections can also be correlated directly with the book, as part siblings.
Since the book preface in the previous example comes before the first part, you can write it as level 1 section if you prefer.
[,asciidoc]
----
[preface]
== Book Preface
This is the preface for the whole book.
=== Preface Subsection
Chinchillas rule the world.
----
Read on to find out how to use special sections as part siblings.
== Special sections as part siblings
In a multi-part book, parts occupy the top level in the hierarchy.
If you were to define a special section at level 1 that follows a part in a multi-part book, it will become a child of that part.
If you want the special section to be owned by the book instead, as a sibling of parts, it must be defined at the top level too.
The AsciiDoc syntax allows special sections in a multi-part book to be defined using a level 0 section title (i.e., `=`).
When the document is parsed, the level of the special section will automatically be adjusted to a level 1 section in the model.
Despite this level change, the special section remains as a sibling of parts in the hierarchy.
The one level of offset (level 0 instead of level 1) is only a hint to the parser to make the special section a sibling of parts.
You can see this syntax used for the appendix in the following example.
[,asciidoc]
----
= Multi-Part Book
:doctype: book
= Part Title
== Chapter Title
[appendix]
= Appendix Title
----
For consistency, it's best to also make special sections part-like if they come before the first part.
However, technically the syntax doesn't require it.
[,asciidoc]
----
= Multi-Part Book
:doctype: book
[preface]
= Book Preface
= Part Title
== Chapter Title
----
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 the part and a special section with subsections after the part.
----
include::example$multipart-book-with-special-sections.adoc[]
----
When you convert this document, notice that the special sections are siblings of the part in the table of contents.
image::multipart-toc-with-special-sections.png[TOC of multi-part book with special sections,350]
Notice that the subsections of the special sections are only a single level below the parent section rather than two levels below.
"#
);