Known Issues and Limitations

At the moment, only block IDs in the shorthand form are supported (e.g., [#install]). For example:

The long-hand (e.g., id=install) and block anchor (e.g., [[install]]) forms are not supported.

When you use a line-based comment in a table, Asciidoctor can no longer accurately track the location of lines, so Assembler’s line-based processing loses track of block images in that table.

For example, when you include this comment in an AsciiDoc table cell:

All block images in the table produce "not found" errors when Assembler generates the merged AsciiDoc file.

The workaround is to use a comment paragraph instead:

This works because, during parsing, it’s discovered as a paragraph. Comment lines are removed immediately, whereas comment paragraphs are removed later. This means the paragraph still “exists” when Asciidoctor processes the remainder of the AsciiDoc table, so block images can still be located.

If a delimited block is unterminated on one of the pages included an an assembly, it can impact the block structure of all remaining pages in the assembly.

For example:

This situation can result in subsequent sections not being found since sections cannot be used inside of delimited blocks. Thus, you are going to want to pay attention to warnings issued by Asciidoctor to ensure all delimited blocks are properly terminated.

Assembler only supports page references that use the xref macro. It does not support page references expressed using the xref shorthand. (The xref shorthand can still be used to create internal references within the page).

For example:

Assembler does not honor attributes declared in the body—​meaning below the document header—​that have an impact on references. That’s because Antora processes the original source, not the converted output. The converter still processes all attribute entries and references, but Antora won’t resolve them when rewriting the source. Rather, Antora rewrites what is visible in the unprocessed AsciiDoc source only.

For example: