Known Issues and Limitations
Shorthand block IDs only
At the moment, only block IDs in the shorthand form are supported (e.g., [#install]
).
For example:
[#install]
== Installation
The long-hand (e.g., id=install
) and block anchor (e.g., [[install]]
) forms are not supported.
Using line comments in tables
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:
// A comment
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:
[comment]
A comment
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.
Unterminated delimited blocks
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:
= Page Title
== Section Title
====
Unterminated example block.
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.
Page references using xref shorthnad
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:
The xref shorthand <<the-page.adoc#>> is not supported.
However, the xref macro xref:the-page.adoc[] is supported.
Attribute entries in the body
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:
= Page Title
== Section
:the-image: image:the-image.svg[]
This inline image {the-image} will not be resolved.