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. Assembler can handle it either way.

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

Assembler can support a book defined in a single AsciiDoc file, but only if it’s the root page, the root level of the assembly is 0, the nav file is empty, and the assembly-style attribute is unset. (You can use an assembly profile to define an empty nav file if you still want navigation in the site).

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 each 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 root page (typically the 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, and you want the preface to have a title, then set the preface-title (or assembly-navtitle) attribute.

The assembly style of the root page of a root level 0 assembly with fused sections defaults to preface unless otherwise specified by the assembly-style attribute. If the root page is a preface, the preface will not have a title unless the preface-title or assembly-navtitle attribute is set. The preface-title attribute can have an empty value.

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.

Any roles and options on the document are propagated to the section in the assembly, so you can use them in the normal way.

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 uncomment the reference to this new page in the nav file provided earlier.

If you prefer to have the root page act as the preface, you can additionally specify the preface title using the preface-title attribute.

The assembly style of the root page of a root level 0 assembly with fused sections defaults to preface unless otherwise specified by the assembly-style attribute. If the root page is a preface, the preface will not have a title unless the preface-title or assembly-navtitle attribute is set. The preface-title attribute can have an empty value.