Asciidoctor PDF Features

Highlights

  • Direct AsciiDoc to PDF conversion

  • Composable, configuration-driven theming system that resembles basic CSS

  • Themable AsciiDoc blocks (e.g., example, admonition, sidebar, etc.)

  • Custom fonts (TTF and limited OTF support)

  • Full SVG support

  • Front and back cover pages

  • Title page

  • Document metadata (title, authors, subject, keywords, etc.)

  • PDF document outline

  • Table of contents with page numbers

  • Configurable page size (e.g., A4, Letter, Legal, etc.) and layout (portrait or landscape)

  • Internal cross reference links

  • Syntax highlighting with Rouge (preferred), Pygments, or CodeRay

  • Page background color or page background image with configurable scaling

  • Page numbering

  • Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)

  • Customizable header and footer running content

  • Section body indent

  • Unbreakable blocks

  • Orphaned section titles avoided (basic support)

  • Autofit verbatim blocks (as permitted by base_font_size_min setting)

  • Table border settings

  • Font-based and image icons

  • Auto-generated index

  • Automatic hyphenation (when enabled)

  • Permissive line breaking for CJK languages

  • Compression / optimization of output file

Known limitations

  • All decimal and hexadecimal character references are supported (e.g., ©). However, the converter only processes a restricted set of named entities. The recognized named entities are as follows: amp, apos, gt, lt, nbsp, and quot (e.g., ').

  • Copying text from a PDF in a way that preserves the original line wrapping is not reliable, particularly in code blocks. To achieve proper rendering, non-visible characters may either be interpreted, inserted, or dropped. This is primarily a limitation of the PDF format, in which text is broken into fragments and positioned at absolute coordinates on the canvas.

  • Footnotes are always displayed as endnotes (at the bottom of the last page of a chapter for books; at the bottom of the last page of the document for all other doctypes). Footnotes cannot be displayed at the current bottom of the page because the PDF generator does not support content reflows (see #85 for reasoning).

  • Table cells that exceed the height of a single page are truncated with a warning (see prawn-table#41).

    • This limitation also applies to description blocks in a horizontal dlist.

  • A rowspan in a table that exceeds the height of a single page will be orphaned and the remaining columns will be truncated (see #403).

  • A column can’t be assigned a width of 0% or a width less than the width of a single character. The converter will skip the table and emit a warning if such a case occurs.

  • A column can’t be set to autowidth if the width of all the other columns in the table meets or exceeds 100%. The converter will skip the table and emit a warning if such a case occurs.

  • An inline image in a table cell will shrink to fit (rather than force the column wider) if the width of the image exceeds the width of the column; you can increase the width of the column using cols or convert the cell to an AsciiDoc table cell and, preferably, use a block image (see #830).

  • An inline image with a percentage width value in an autowidth table cell is resized relative to its intrinsic width. The space reserved for the image matches its intrinsic width. This matches the behavior of HTML.

  • Prawn does not support double-wide box drawing glyphs correctly, so box drawings aren’t aligned properly in verbatim blocks (see prawn#1002).

  • Orphan and widow support is limited to delimited blocks, block images, and admonitions; therefore, a page break may occur between a section title and its first block of content

    • to avoid an orphaned section title, you can add the breakable option to the section

    • to avoid an orphaned caption on a table, add the breakable option to the table

  • If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break.

  • The float attribute on an image (i.e., an image float) is only supported for block images, not inline images. The converter will clear the float at the next non-paragraph or when the paragraph content clears the bottom of the image. See Wrap code blocks around an image float to learn how to wrap non-paragraph blocks around an image float.

  • Multiple columns are not supported in the book doctype.

  • You cannot use inline HTML (like a link or emphasized text) in a source block that also uses syntax highlighting. These two technologies don’t mix in the PDF generation process due to how the syntax highlighters work.

  • Verse blocks do not use a fixed-width font by default, but you can control this setting using the theme.

  • Cannot use remote inline image in the doctitle or a section title with an automatic ID.

  • Cannot use custom subs that introduce text formatting (e.g., subs=+quotes) on a source block when source-highlighter is set. The converter will automatically remove the formatting so the source can be recognized and highlighted properly by the syntax highlighter.