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., ) 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.