Assembler Use Cases

When organizing your book, think about how granular you want the content on the website to be. That’s your starting point. For a shorter book, you might decide to make one page per chapter. For a longer book, you may want to split out the top-level sections of each chapter into separate pages.

As a rule of thumb, any top-level section in the assembly must be a page. Therefore, if your book has parts, then each part (or part-like section) must be a page (and tagged as a part). If your book does not have parts, then each chapter (or chapter-like section) must be a page.

The AsciiDoc include directive gives you the flexibility to chunk the source into even more fine-grained units without introducing additional pages. For instance, you might consider organizing the top-level sections as partials in the partials folder and include them into the appropriate chapter using the include directive.

To produce a book, configure Assembler to fuse sections from each page with the hierarchy defined by the navigation. This ensures that all sections are represented in the table of contents (TOC) of the export. Of course, you’ll want to enable the automatic toc as well.

See the documentation for the fuse value for more details.

Here’s the component version descriptor for the book:

Once you’ve decided on the granularity of your content, you can start setting up your pages and navigation.

Let’s assume you’re going to make one page per chapter. Here’s how your navigation file might look:

You can optionally create a start page to define assembly header attributes, such as authors, and/or the preface. In the simplest case, the start page repeats the book title.

If the start page serves as the preface, then use the preface title as the page title (or set the preface-title attribute).

Here’s how the first chapter might begin:

Notice that the chapter title is a level 0 document title. Assembler automatically shifts its section level, as well as those of its descendants, so it becomes a chapter in the assembly.

For the appendix, you’ll need to mark it in a special way. That’s because AsciiDoc does not support using the block style (i.e., [appendix]) on the document title. Instead, you’ll use the assembly-style document attribute to denote the special section style. This attribute is only intended as metadata for Assembler and is not included in the assembly itself.

You can use the assembly-style attribute to designate any special section in a book, such as colophon, dedication, index, etc.

Since the filename root index has special meaning in web publishing, you’re encouraged to name the file of the page for your index section something more descriptive, such as book-index (or index_).

You can now use an exporter extension such as @antora/pdf-extension to build the PDF for your book in addition to the website. If you need to produce other formats, register those corresponding extensions as well.

Assembler also gives you the means of creating a multi-part book. In this case, you nest the chapter pages in the navigation under the part pages:

To instruct Assembler to make a part, you need to denote it using the assembly-style attribute in that source file.

To make the appendix chapters siblings of the last part instead of nested inside of it (but still act as chapters), you’ll once again need to make use of the assembly-style attribute.

The -part suffix instructs Assembler to keep the document title as a level 0 section while also setting the style on that section. (Assembler will automatically adjust the section levels under the document title so they conform to the AsciiDoc syntax rules). If you want the special section to be added as a child of a part, don’t include the -part suffix.

In the same way, if you want to add a special section at the level of a part anywhere else in the document, you append the -part suffix to the style. For example, let’s add a preface at the start of the book.

You’ll need to add this new page to the nav file. Alternately, if you prefer to have the start page act as the preface, you can additionally specify the preface title using the preface-title attribute.

If you don’t specify the preface-title attribute in this case, the preface will not have a title and thus won’t appear in the TOC. An alternate approach is to define the preface title using the document title (i.e., page title).