DOCSEARCHbyAlgolia
Submit Docs

Asciidoctor PDF

repository·main·Indexed 22 days ago

https://github.com/asciidoctor/asciidoctor-pdf

A native PDF converter for AsciiDoc that converts documents directly to PDF without intermediate formats like DocBook or LaTeX, utilizing the Prawn gem for PDF generation. It includes a CLI for conversion, a PDF optimizer via `asciidoctor-pdf-optimize`, and extensive theme and attribute configuration for styling tables, images, page layouts, and Table of Contents.

Tokens
66.1K
Snippets
244
Records
400
Agent score
73%

What's inside asciidoctor-pdf

  1. Overview of Asciidoctor PDF features

    main

    Asciidoctor PDF is a native converter that transforms AsciiDoc documents directly into PDF files. Key capabilities include:

    • Theming: A composable, configuration-driven theming system (similar to CSS) that allows for styling AsciiDoc blocks like examples, admonitions, and sidebars.
    • Layout & Design: Support for front/back covers, title pages, configurable page sizes (A4, Letter, etc.), portrait/landscape orientation, and double-sided (prepress) printing with alternating margins.
    • Content Elements: Full SVG support, custom fonts (TTF/limited OTF), syntax highlighting (Rouge, Pygments, or CodeRay), and font-based or image icons.
    • Navigation: PDF document outlines, tables of contents with page numbers, internal cross-reference links, and auto-generated indexes.
    • Advanced Formatting: Automatic hyphenation, CJK line breaking, page background colors/images, and customizable headers and footers.
    • Optimization: Compression and optimization of the output PDF file.

  3. Understand line-height and line-height-length

    main

    The line-height key controls the spacing between lines.

    The line-height-length key is a utility property used internally by the theme to compute the base-line-height from the base font size. While you don't need to use this specific utility in your own theme, you can use it to perform calculations. For example, you can set base-line-height using the formula: $base-line-height-length / $base-font-size.

  4. Configure line height and compensate for font built-ins

    main

    The line-height key is a multiplier of the font-size. It controls the spacing between wrapped lines.

    • 1: Line height equals font height (lines may touch if the font has built-in spacing).
    • 2: Line height is twice the font height.
    • Values < 1: Risk causing text in adjacent lines to overlap.

    Compensating for Font Built-ins: Many fonts (like the Noto family) have built-in line height. For example, Noto has a built-in multiplier of 1.36. If you want a visual line height of 1.5, you should set the line-height in your theme to 1.1 to compensate for the font's internal spacing.

  5. Exclude sections from the TOC

    main

    You can selectively exclude sections from the TOC using the toclevels block attribute:

    1. Exclude a section and all its descendants: Set toclevels to a value less than the section's own level. For example, using [toclevels=0] on a top-level section will remove it from the TOC.
    2. Exclude only descendants: Set toclevels to the current level of the section. This keeps the section in the TOC but prevents its sub-sections from appearing.

    Constraint: You cannot include a section in the TOC if its parent has already been excluded.

  6. Extend a theme using the `extends` key

    main

    You can create a custom theme by extending one or more existing themes using the extends key in your YAML theme file. This allows you to inherit styles and only override specific properties.

    Rules for extends

    • Placement: The extends key must be the first key in your theme file.
    • Format: It accepts either a single String or an Array of strings.
    • Resolution Logic:
      • default: Resolves to the built-in default theme.
      • Absolute path: Used as provided.
      • ./: Resolves to a file relative to the current theme file.
      • Filename (no prefix): Resolved relative to the pdf-themesdir attribute.
      • Suffix: If the filename does not have a .yml extension, -theme.yml is appended implicitly.

    Inheritance Order

    1. The current theme starts empty.
    2. Referenced files are loaded in the order provided in the array.
    3. For each loaded theme, its flattened keys are overlaid onto the previous theme's keys.
    4. Finally, the keys defined in your current file are loaded, overriding any inherited values.
    extends:
- default
- ./brand-theme.yml

  7. How inline image height affects line spacing

    main

    Asciidoctor PDF manages line height based on the resolved height of the inline image:

    • Small images: If the image height is $\le$ 1.5 times the line height, the image is vertically centered in the line and does not increase the line height.
    • Large images: If the image height exceeds 1.5 times the line height, the line height is increased (via an invisible placeholder text) to accommodate the image. In this case, the surrounding text aligns to the bottom of the image.
    • Page overflow: If an image's height exceeds the height of the page, it will be scaled down to fit on a single page, which may cause the image to advance to the next page.

  11. How border-width and border-left-width interact in quote blocks

    main

    In Asciidoctor PDF quote blocks, the application of borders depends on the priority of the width keys:

    1. Left-side border only: If border-left-width is set to a non-zero value, the border is applied exclusively to the left side of the quote block.
    2. Full border: If border-left-width is zero (or not set), and border-width is set to a non-zero value, the border is drawn around the entire quote block.

  12. Understand Asciidoctor PDF limitations

    main

    When designing documents for Asciidoctor PDF, be aware of the following constraints:

    Tables

    • Truncation: Table cells exceeding a single page height are truncated with a warning. Rowspans that exceed a page height will result in orphaned rows and truncated columns.
    • Width Constraints: Columns cannot have a width of 0% or a width smaller than a single character. autowidth cannot be used if other columns already meet or exceed 100% width.
    • Images in Tables: Inline images in table cells will shrink to fit the column width rather than forcing the column wider. To prevent this, use cols to set a specific width or use a block image in an AsciiDoc table cell.

    Text and Formatting

    • Footnotes: Footnotes are always rendered as endnotes (at the end of the chapter for books, or the end of the document for other doctypes) and cannot be placed at the bottom of the current page.
    • Syntax Highlighting: You cannot use inline HTML (like links or emphasis) inside a source block that uses syntax highlighting. Additionally, custom substitutions (e.g., subs=+quotes) are automatically removed from source blocks to allow the highlighter to function.
    • Named Entities: Only a restricted set of named entities are recognized: amp, apos, gt, lt, nbsp, and quot.