= Asciidoctor PDF Features
:navtitle: Features

== Highlights

* Direct AsciiDoc to PDF conversion
* Composable, xref:theme:index.adoc[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.)
* xref:pdf-outline.adoc[PDF document outline]
* xref:toc.adoc[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 xref:background-images.adoc[page background image] with configurable scaling
* xref:page-numbers.adoc[Page numbering]
* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
* xref:theme:add-running-content.adoc[Customizable header and footer running content]
* Section body indent
* xref:breakable-and-unbreakable.adoc[Unbreakable blocks]
* Orphaned section titles avoided (basic support)
* Autofit verbatim blocks (as permitted by `base_font_size_min` setting)
* Table border settings
* xref:icons.adoc[Font-based and image icons]
* Auto-generated index
* Automatic hyphenation (when enabled)
* Permissive line breaking for CJK languages
* Compression / optimization of output file

[#limitations]
== 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 {url-project-issues}/85#issuecomment-577412975[#85^] for reasoning).
* Table cells that exceed the height of a single page are truncated with a warning (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41^]).
* A rowspan in a table that exceeds the height of a single page will be orphaned and the remaining columns will be truncated (see {url-project-issues}/403#issuecomment-1133840210[#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 {url-project-issues}/830[#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 https://github.com/prawnpdf/prawn/issues/1002[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 xref:breakable-and-unbreakable.adoc[breakable option] to the section
 ** to avoid an orphaned caption on a table, add the xref:breakable-and-unbreakable.adoc[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 xref:extend:use-cases.adoc#wrap-code-blocks-around-image[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 xref:theme:verse.adoc[using the theme].
* 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.