Partials, Examples and Attachments

Use the include:: directive with the partial$ family. The file coordinate is the path inside partials.

Source: Antora docs: Include a partial

The directive must start a line. Surround it with blank lines to get a standalone block, or put it directly against other lines to attach the content to a block. The partial is converted after insertion in the context of the including page, so {product-name} was taken from the asciidoc.attributes of antora.yml, and the built page shows "Install Pocket Units with dotnet add package PocketUnits --version 2.0.0". If a partial sets an attribute, the attribute is available in the page from that point and overrides a same-named attribute of the page header or the descriptor.

A partial may contain section headings. The leveloffset attribute shifts them to fit the place of the directive. With leveloffset=+1, a partial whose title is = Shared Heading was rendered as a level-two section:

The default family of an include is page$, so the family is always required. Other modules and components are reached by adding coordinates to the resource ID, like in xrefs (see resource IDs and xrefs):

Source: Antora docs: Include a partial

The first line names another module of the same component version, the second a module of another component version and the third the ROOT module of that version, which can be omitted although the colon stays. Without a version Antora uses the latest version of the target component. Xrefs, images and nested includes inside a partial are resolved against the page that includes it, so write them with coordinates valid in every including context. These forms are taken from the official documentation and were not all built here; the unqualified forms were.

Select a region with tag and several regions with tags, separated by semicolons. The regions are concatenated in the order they appear in the file.

The built result of tag=usage contained only the conversion line. With tags=usage;print it contained the two lines one after the other with the marker lines removed, and the using line and the blank lines were left out:

Source: Antora docs: Include an example

The syntax of tag, tags and lines is the Asciidoctor one. The Antora page refers to the Asciidoctor documentation instead of repeating it.

lines takes line numbers and ranges, separated by semicolons (commas need quotes around the value). lines=1;4..5 includes line 1 and the lines 4 to 5. Lines are counted in the example file, and unlike tags, they keep any tag marker lines that fall inside the range: the build of lines=1;4..5 ended with the // end::usage[] comment, which is not what you want in a listing. Prefer tags, which survive edits of the file, and use line ranges only for files you do not control, such as a generated file.

The indent attribute rewrites the left margin of the included lines. indent=0 removes common leading whitespace, which is useful for a method body taken from a class. It was set in the example above but made no difference, because the lines were not indented.

Source: Antora docs: Include an example

The first line was built. The other two follow the forms of the official documentation and were not executed here. Without a version Antora includes the latest version of the component when the target is in another component.

When the family is missing, the include falls back to page$ and cannot find the file:

Source: Antora docs: Include an example

The page build logged the error target of include not found: convert.cs and the page showed the text "Unresolved include directive in modules/ROOT/pages/experiments.adoc - include::convert.cs[]" in place of the listing.

An include:: line inside a listing block is still processed. To show the directive itself, as this page does, put a backslash in front of it. The built page shows the line without the backslash. A listing that itself contains a ---- line must be delimited by .... instead.

Use the xref macro with the attachment$ family. Without the family Antora treats the target as a page.

The generated links were <a href="_attachments/units.csv" class="xref attachment">unit table</a> and the same for the archive. A fragment cannot be added to an attachment resource ID. Attachments have no default reference text. If the brackets are empty Antora shows the resource ID, as in attachment$pocket-units-sample.zip, so always give a text. Whether the browser downloads the file or displays it depends on the file type and the browser settings.

Source: Antora docs: Attachments

Attachment links can also be used in navigation files, as shown in Navigation. Other modules and versions are reached the same way as for the other families:

Source: Antora docs: Attachments

These forms are given in the official documentation. They were not built here.

Because attachments are plain files, a page can also include a text-based one with include:: and the attachment family. The official documentation mentions that the optional attributes of the include directive work for this case. This was not built here.