Asciidoctor PDF: A native PDF converter for AsciiDoc

Asciidoctor PDF is a native PDF converter for AsciiDoc. It bypasses the requirement to generate an intermediary format such as DocBook, Apache FO, or LaTeX. Instead, you can use this extension to convert your documents directly from AsciiDoc to PDF. Its aim is to take the pain out of creating PDF documents from AsciiDoc.

• Overview
• Highlights
• Known Limitations
• Prerequisites
• Getting Started
• Themes
• Support for Non-Latin Languages
• Font-Based Icons
• Image Paths
• Image Scaling
• Background Image Positioning
• Fonts in SVG Images
• Supporting Additional Image File Formats
• Importing PDF Pages
• Interdocument Xrefs
• STEM Support
• Skipping Passthrough Content
• Shaded Blocks and Performance
• Autofitting Text
• Autowidth Tables
• Printing Page Ranges
• Title Page
• Table of Contents
• Index Catalog
• Optimizing the Generated PDF
• Contributing
• Resources
• Authors
• Copyright

Asciidoctor PDF is an Asciidoctor extension that converts an AsciiDoc document directly to a PDF document. The style and layout of the PDF is controlled by a dedicated theme file. To the degree possible, this converter supports all the features of AsciiDoc that are supported by the built-in converters. However, there are certain limits imposed by the PDF format and the PDF library this extension uses.

Under the covers, Asciidoctor PDF uses the Prawn gem and its extensions (e.g., prawn-svg and prawn-table) to generate the PDF document. Prawn is a general purpose PDF generator for Ruby that features high-level APIs for common needs like setting up the page and inserting images and low-level APIs for positioning and rendering text and graphics.

Prawn takes the pain out of creating (basic) PDF documents. Likewise, Asciidoctor PDF takes the pain out of creating PDF documents directly from AsciiDoc. Skip ahead to Getting started to start putting Asciidoctor PDF use. But don’t miss the Highlights to get a preview of what’s possible.

• Direct AsciiDoc to PDF conversion

• Configuration-driven theme (style and layout)

• Custom (TTF) fonts

• Full SVG support (thanks to prawn-svg)

• PDF document outline (i.e., bookmarks)

• Title page

• Table of contents page(s)

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

• Configurable page size (e.g., A4, Letter, Legal, etc)

• Internal cross reference links

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

• Cover pages

• Page background color or page background image with named scaling

• Page numbering

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

• Customizable running content (header and footer)

• “Keep together” blocks (i.e., page breaks avoided in certain block content):

  • Explicitly delimited blocks other than open blocks

  • Open blocks with the "unbreakable" option [%unbreakable]

• Orphaned section titles avoided

• Autofit verbatim blocks (as permitted by base_font_size_min setting)

• Table border settings honored

• Font-based icons

• Auto-generated index

• Automatic hyphenation (when enabled)

• Permissive line breaking for CJK languages

• Compression / optimization of output file

• Footnotes are always displayed as endnotes (at the end of chapter for books; at the end of document for all other doctypes). Footnotes cannot be displayed at the 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 will be truncated (see prawn-table#41).

• Inline images in table cells must fit within available column width or a Prawn::Errors::CannotFit error will be thrown (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1608 for workarounds).

• Columns cannot be assigned a 0% width (or a width less than the width of a single character); in the same vein, a column cannot be set to autowidth if width of all other columns meets or exceeds 100%; the result is that the converter with throw a Prawn::Errors::CannotFit error.

• An inline image in a table cell will not force the column wider if the width of the image exceeds the width of the column; either reduce the image width using pdfwidth or increase the width of the column using cols; another solution is to convert the cell to an AsciiDoc table cell (see https://github.com/asciidoctor/asciidoctor-pdf/issues/830).

• Must use development version of prawn-table for autowidth to work on table head row.

• Must use development version of prawn for error to include font name when requested font style is missing.

• AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing).

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

• Orphan / widow support is limited; a page break can occur between a section title and its section content, a table caption and the caption, etc.; use a manual page break to avoid.

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

• Images cannot float.

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

All that’s needed is Ruby 2.5 or better (or JRuby 9.2 or better) and a few Ruby gems (including at least Asciidoctor 2.0.0), which we explain how to install in the next section.

To check if you have Ruby available, use the ruby command to query the version installed:

Make sure this command reports a Ruby version that’s at least 2.5. If so, you may proceed.

System Encoding

chcp 65001

You can get Asciidoctor PDF by installing the published gem. You can also run the code from source if you want to use a development version or participate in development.

Install the Published Gem

$ gem install asciidoctor-pdf

ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory.

$ gem which asciidoctor-pdf

$ command -v asciidoctor-pdf

$ gem install rouge

$ gem install pygments.rb

$ gem install coderay

:source-highlighter: rouge

source 'https://rubygems.org'

gem 'asciidoctor-pdf'
gem 'prawn', github: 'prawnpdf/prawn'
gem 'prawn-table', github: 'prawnpdf/prawn-table'

$ bundle config set --local path .bundle/gems && bundle

$ bundle exec asciidoctor-pdf -v

Run the Application

$ asciidoctor-pdf -v

An Example AsciiDoc Document

Convert AsciiDoc to PDF

You’ll need the rouge gem installed to run this example since it uses the source-highlighter attribute with the value of rouge.

$ asciidoctor-pdf basic-example.adoc

$ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc

Figure 1. Example PDF document rendered in a PDF viewer

The layout and styling of the PDF is driven by a YAML configuration file. To learn how the theming system works and how to create and apply custom themes, refer to the Asciidoctor PDF Theming Guide. You can use the built-in theme files, which you can find in the data/themes directory, as examples.

If you’ve enabled a source highlighter, you can control the style (aka theme) it applies to source blocks using the coderay-style, pygments-style, and rouge-style attributes, respectively. For example, to configure Rouge to use the built-in monokai theme, run Asciidoctor PDF as follows:

It’s possible to develop your own theme for Rouge. Refer to the Asciidoctor PDF Theming Guide for details.

Asciidoctor can process the full range of characters in the UTF-8 character set. That means you can write your document in any language, save the file with UTF-8 encoding (that’s important!), and expect Asciidoctor to convert the text properly. But you still need a font that provides the glyphs for those characters.

When converting a document with Asciidoctor PDF, you may notice that some glyphs for certain languages, such as Chinese, are missing from the PDF. PDF is a “bring your own font” kind of system. In other words, the font you provide must provide glyphs for all the characters used. There’s no one font that supports all the world’s languages (though some, like Noto Serif, certainly come close). Even if there were such a font, bundling that font with the main gem would make it enormous. It would also severely limit the style choices in the default theme, which targets Latin-based languages. Therefore, we’re taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK. Read on to find out how to use these themes.

Asciidoctor PDF provides a built-in theme that provides a broad range of characters in the CJK charsets, so you can start with that theme:

Notice the -a scripts=cjk option. That’s important. It tells the converter to insert break opportunities between CJK characters so that the line wraps properly when mixing English and a CJK language like Japanese.

If the built-in theme with the fallback font doesn’t go far enough, you’ll need to use a theme that is optimized for CJK text. You can get such a theme by installing the asciidoctor-pdf-cjk-kai_gen_gothic gem. The asciidoctor-pdf-cjk-kai_gen_gothic project provides themes optimized for CJK languages based on the kai_gen_gothic font. See the asciidoctor-pdf-cjk-kai_gen_gothic project README for detailed setup instructions.

Once you have that gem installed (and the fonts), you need to tell Asciidoctor PDF to use one of the themes. If you’re converting a document that is primarily written in Japanese, you’d run Asciidoctor PDF as follows:

You also have to option of creating your own theme gem that uses fonts of your choice. For example, if you want to use the asciidoctor-pdf-cjk-kai_gen_gothic gem to fetch fonts, but then use them in your own theme, here’s how you’d do it.

1. Install the asciidoctor-pdf-cjk-kai_gen_gothic gem:

   $ gem install asciidoctor-pdf-cjk-kai_gen_gothic

2. Download / install the fonts:

   $ asciidoctor-pdf-cjk-kai_gen_gothic-install

3. Create a theme that extends the default theme:

   extends: default
   font:
     catalog:
       KaiGen Gothic JP:
         normal: KaiGenGothicJP-Regular.ttf
         bold: KaiGenGothicJP-Bold.ttf
         italic: KaiGenGothicJP-Regular-Italic.ttf
         bold_italic: KaiGenGothicJP-Bold-Italic.ttf
       M+ 1mn:
         normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
         bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
         italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
         bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
     fallbacks:
     - KaiGen Gothic JP
   base:
     font-family: KaiGen Gothic JP
   heading:
     font-family: $base-font-family
   abstract:
     title:
       font-family: $heading-font-family
   sidebar:
     title:
       font-family: $heading-font-family

4. Load your theme when running Asciidoctor PDF:

   $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./jp-theme.yml -a pdf-fontsdir=`ruby -r asciidoctor-pdf-cjk-kai_gen_gothic -e "print File.expand_path '../fonts', (Gem.datadir 'asciidoctor-pdf-cjk-kai_gen_gothic')"` document.adoc

The -a pdf-fontsdir option is important to tell Asciidoctor PDF where to find your custom fonts.

Rather than using the installer from the asciidoctor-pdf-cjk-kai_gen_gothic gem, you can download fonts whatever way you choose. When using your own fonts, be sure to consult the Preparing a Custom Font section of the theming guide to find recommended modifications.

You can use icons in your PDF document using any of the following icon sets:

• fa - https://fontawesome.com/v4.7.0/icons (default)

• fas - Font Awesome - Solid

• fab - Font Awesome - Brands

• far - Font Awesome - Regular

• fi - Foundation Icons

• pf - Payment font

The fa icon set is deprecated. Please use one of the other three FontAwesome icon sets.

You can enable font-based icons by setting the following attribute in the header of your document:

If you want to override the font set globally, also set the icon-set attribute:

Here’s an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence (assuming the icon-set is set to `pf):

You can use the set attribute on the icon macro to override the icon set for a given icon.

You can also specify the font set using the following shorthand.

In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).

You can enable use of fonts during PDF generation (instead of in the document header) by passing the icons attribute to the asciidoctor-pdf command.

Icon-based fonts are handled by the prawn-icon gem. To find a complete list of available icons, consult the prawn-icon repository.

Images are resolved at the time the converter runs. That means they need to be located where the converter can find them.

Relative images paths in the document are resolved relative to the value of the imagesdir attribute. This is effectively the same as how the built-in HTML converter works when the data-uri attribute is set. The imagesdir is blank by default, which means relative images paths are resolved relative to the input document. Relative images paths in the theme are resolved relative to the value of the pdf-themesdir attribute (which defaults to the directory of the theme file). The imagesdir attribute is not used when resolving an image path in the theme file. Absolute image paths are used as is.

If the image is an SVG, and the SVG includes a nested raster image (PNG or JPG) with a relative path, that path is resolved relative to the directory that contains the SVG.

The converter will refuse to embed an image if the target is a URI (including image references in an SVG) unless the allow-uri-read attribute is enabled via the CLI or API.

If you use a linked image in an SVG, the width and height of that image must be specified. Otherwise, the SVG library will fail to process it.

Asciidoctor Diagram Integration

Since PDF is a fixed-width canvas, you almost always need to specify a width to get the image to fit properly on the page. There are five ways to specify the width of an image, listed here in order of precedence:

The image is always sized according to the explicit or intrinsic width, then its height is scaled proportionally. The height of the image is ignored by the PDF converter unless the height of the image exceeds the content height of the page. In this case, the image is scaled down to fit on a single page.

If you want a block image to align to the boundaries of the page (not the content margin), specify the align-to-page option (e.g., opts="align-to-page"). This is most useful when using vw units because you can make the image cover the entire width of the page.

Images in running content and page background images also support the fit attribute (when specified using the image macro). See Background Image Sizing for details.

Using the pdfwidth Attribute

Specifying a default width

image:
  width: 100%

Inline Image Sizing

Background Image Sizing

In addition to scaling, background images for cover pages, content pages, and the title page support positioning via the position attribute. The position attribute accepts a syntax similar to the background-position property in CSS, except only the keyword positions are supported. The position consists of two values, the vertical position and the horizontal position (e.g., top center). If only one value is specified (e.g., top), the other value is assumed to be center. If the position attribute is not specified, the value is assumed to be center center (i.e., the image is centered on the page).

The following table provides a list of the vertical and horizontal positioning keywords that are supported. You can use any combination of these keywords to position the image.

Here’s an example of how to place a background image at the top center of every page:

Here’s how to move it to the bottom right:

If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.

Asciidoctor PDF uses prawn-svg to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.

Actually, it’s not accurate to say that prawn-svg embeds the SVG. Rather, prawn-svg is an SVG renderer. prawn-svg translates an SVG into native PDF text and graphic objects. You can think of the SVG as a sequence of drawing commands. The result becomes indistinguishable from other PDF objects.

What that means for text is that any font family used for text in the SVG must be registered in the Asciidoctor PDF theme file (and thus with Prawn). Otherwise, Prawn will fallback to using the closest matching built-in (afm) font from PDF (e.g., sans-serif becomes Helvetica). Recall that afm fonts only support basic Latin. As we like to say, PDF is bring your own font.

If you’re using Asciidoctor Diagram to generate SVGs to embed in the PDF, you likely need to specify the default font the diagramming tool uses. Let’s assume you are making a plantuml diagram.

To set the font used in the diagram, first create a file named plantuml.cfg and populate it with the following content:

Next, pass that path to the plantumlconfig attribute in your AsciiDoc document (or set the attribute via the CLI or API):

Clear the cache of your diagrams and run Asciidoctor PDF with Asciidoctor Diagram enabled. The diagrams will be generated using Noto Serif as the default font, and Asciidoctor PDF will know what to do.

The bottom line is this: If you’re using fonts in your SVG, and you want those fonts to be preserved, those fonts must be defined in the Asciidoctor PDF theme file.

In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it. To perform this work, Asciidoctor delegates to the underlying libraries. Prawn provides support for reading JPG and PNG images. prawn-svg brings support for SVG images. Without any additional libraries, those are the only supported image file formats.

If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG—​and you don’t want to convert those images to a supported format—​you must install the prawn-gmagick (>= 0.0.9) Ruby gem. prawn-gmagick is an extension for Prawn based on GraphicsMagick that adds support for all the image formats recognized by that library. prawn-gmagick has the added benefit of significantly reducing the time it takes to generate a PDF containing a lot of images.

The prawn-gmagick gem uses native extensions to compile against GraphicsMagick. This system prerequisite limits installation to Linux and OSX. Please refer to the README for prawn-gmagick to learn how to install it.

Once this gem is installed, Asciidoctor automatically loads it, then delegates to it to handle all image embedding. In addition to support for additional image file formats, this gem also speeds up image processing considerably. We highly recommend using this gem if you’re able to install it.

In addition to using a PDF page for the front or back cover, you can also insert a PDF page at an arbitrary location. This technique is useful to include pages that have complex layouts and graphics prepared in a specialized design program (such as Inkscape), which would otherwise not be achievable using this converter. One such example is an insert such as an advertisement or visual interlude.

To import the first page from a PDF file, use the block image macro with the PDF filename as the image target.

The converter will insert the page from the PDF as a dedicated page that matches the size and layout of the page being imported (no matter where the block image occurs). Therefore, there’s no need to put a manual page break (i.e., <<<) around the image macro.

By default, this macro will import the first page of the PDF. To import a different page, specify it as a 1-based index using the page attribute.

You can import multiple pages either using multiple image macros or using the pages attribute. The pages attribute accepts individual page numbers or page number ranges (two page numbers separated by ..). The values can be separated either by commas or semi-colons. (The syntax is similar to the syntax uses for the lines attribute of the AsciiDoc include directive).

Pages are imported in the order listed.

To see a practical example of how to use this feature, refer to the blog post Importing PDF Pages in asciidoctor-pdf.

An xref to another AsciiDoc document (i.e., an interdocument xref) will either become a link to the PDF file generated from that source document or an internal link to an anchor within the current document. Which one it becomes depends on whether the target has been included into the current document. These section describes these two scenarios.

Referencing Another Document

A link to xref:b.adoc[b].

A link to xref:b.adoc#chapter-b[b].

Linking to a named anchor isn’t supported by all PDF viewers. Some viewers (like Firefox) only support relative links when the PDF is accessed through a web server. To verify it’s working, test the PDF in Firefox and served through a local web server.

A link to page 2 of xref:b.adoc#page=2[b].

Converting Interdocument Xrefs to Internal Xrefs

include::chapters/chapter-1.adoc[]

<<chapters/chapter-1.adoc#_anchor_name,Destination in Chapter 1>>

= Book Title
:doctype: book

include::chapters/chapter-1.adoc[]

include::chapters/chapter-2.adoc[]

== Chapter 1

We cover a little bit here.
The rest you can find in <<chapters/chapter-2.adoc#_chapter_2,Chapter 2>>.

== Chapter 2

Prepare to be educated.
This chapter has it all!

To begin, jump to <<chapters/chapter-2/first-steps.adoc#_first_steps,first steps>>.

<<<

include::chapter-2/first-steps.adoc[]

=== First Steps

Let's start small.

Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros (i.e., asciimath and latexmath). That’s because Asciidoctor core doesn’t process the STEM content itself. It just passes it through to the converter. In the HTML output, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the equations in the browser when the page is loaded. The HTML converter simply wraps the equations in special markup so MathJax can find them.

In order to insert a rendered equation into the PDF, the toolchain has to parse the equations and convert them to a format the PDF writer (Prawn) can understand. That typically means converting to an image.

The recommended solution is an extension named Asciidoctor Mathematical, which we’ll cover in this document.

Another solution, which is still under development, uses Mathoid to convert STEM equations to images. Mathoid is a library that invokes MathJax using a headless browser, so it supports both asciimath and latexmath equations. That prototype can be found in the Asciidoctor extensions lab.

Asciidoctor Mathematical

$ asciidoctor-pdf -r asciidoctor-mathematical sample.adoc

require 'asciidoctor-mathematical'

Asciidoctor.convert_file 'sample.adoc', safe: :safe

$ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc

Asciidoctor PDF does not support arbitrary passthrough content. While the basebackend for the PDF converter is html, it only recognizes a limited subset of inline HTML elements that can be mapped to PDF (e.g., a, strong, em, code, ). Therefore, if your content contains passthrough blocks or inlines, you most likely have to use a conditional preprocessor to skip them (and make other arrangements).

Here’s an example of how to skip a passthrough block when converting to PDF:

Here’s an example of how to only enable a passthrough block when converting to HTML5:

Certain blocks are rendered with a shaded background, such as verbatim (listing, literal, and source), sidebar, and example blocks. In order to calculate the dimensions of the shaded region, Asciidoctor PDF has to “dry run” the block to determine how many pages it consumes. While this strategy has a low impact when processing shorter blocks, it can drastically deteriorate performance when processing a block that spans dozens of pages. As a general rule of thumb, you should avoid using shaded blocks which span more than a handful of pages.

Verbatim blocks often have long lines that don’t fit within the fixed width of the PDF canvas. And unlike on the web, the PDF reader cannot scroll horizontally to reveal the overflow text. Therefore, the long lines are forced to wrap. Wrapped lines can make the verbatim blocks hard to read or even cause confusion.

To help address this problem, Asciidoctor PDF provides the autofit option on all verbatim (i.e., literal, listing and source) blocks to attempt to fit the text within the available width. When the autofit option is enabled, Asciidoctor PDF will decrease the font size (as much as it can) until the longest line fits without wrapping.

Here’s an example of the autofit option enabled on a source block:

If you want to enable the autofit option globally, set the autofit-option document attribute in the document header (or somewhere before the relevant blocks):

Asciidoctor PDF does support autowidth tables. However, the behavior differs from HTML when the content forces the table to the page boundary. The behavior, which is handled by the prawn-table library, is explained in this section.

If the natural width of all columns (based on the width of the cell content) is less than the width of the page, it behaves as you’d expect. Each column is assigned the width it needs to prevent the content from wrapping.

However, when the natural width of all columns exceeds the width of the page, the behavior may not be what you expect. What prawn-table does is compute how to arrange the table on an infinite canvas, where each column can have a width no greater than the width of the page. Then, it reduces the width of the table by reducing the width of each column proportionally. As a result, columns which reported the width necessary to render without wrapping now no longer do.

The reason this compression is not performed like in HTML is because prawn-table has no awareness of words. Thus, it doesn’t know how to redistribute with width intelligently.

To protected against truncation or insufficient width errors, prawn-table wraps text by character. That’s why the last character in the cell can end up getting wrapped. (There’s a small amount of tolerance built in to prawn-table to address some edge cases, but it’s not sufficient to handle all of them).

For the reason just explained, you should be extremely careful with relying on autowidth tables in Asciidoctor PDF, especially when the natural content of the cells forces the table to page boundary. Let experience be your guide.

The print dialog doesn’t understand the page numbers labels (which appear in the running content). Instead, it only considers physical pages. Therefore, to print a range of pages as they are labeled in the document, you need to add the number of front matter pages (i.e., the non-numbered pages) to the page number range in the print dialog.

For example, if you only want to print the first 5 pages labeled with a page number (e.g., 1-5), and there are 2 pages before the page labeled as page 1, you need to add 2 to both numbers in the range, giving you a physical page range of 3-7. That’s the range you need to enter into the print dialog.

Unlike other converters, the PDF converter introduces a dedicated title page at the start of the document. The title page contains the doctitle, author, date, and revision info. If a front cover image is specified, the title page comes after the front cover. The title page can be styled using the theme and/or reserved page attributes.

The title page is enabled if either of these conditions are met:

• The document has the book doctype.

• The title-page attribute is set (with an empty value) in the document header.

When the title page is enabled, the table of contents (aka TOC) also gets is own page (or pages, if necessary).

The table of contents (TOC) is not included by default. The TOC is only included if the toc attribute is set on the document. The value of this attribute determines the placement. If a value is not specified, the placement defaults to auto, which is directly after the document title.

For documents that have the book doctype, the TOC is inserted using discrete pages between the title page and the first page of content. For all other doctypes (unless the title-page attribute is set), the TOC is inserted in the flow of text. If a placement is not specifie, that location is between the document title and the first block of content.

While the table of contents is not included by default, the PDF outline is always included. The toclevels attribute controls the depth of both the TOC and the PDF outline (regardless of whether the TOC is enabled). The depth of the outline can be controlled independently using the outlinelevels attribute.

Asciidoctor PDF supports generating an index catalog that itemizes all index terms defined in the document, allowing the reader to navigate the document by keyword.

To get Asciidoctor PDF to generate an index, add a level-1 section annotated with the index style near the end of your document. The converter will automatically populate the catalog with the list of index terms in the document, organized by first letter.

You can use any text you want for the title of this section. The only restriction is that no index terms may be defined below this section.

How Index Terms are Grouped and Sorted

require 'asciidoctor-pdf'

module Asciidoctor::PDF
  IndexCatalog.prepend (::Module.new do
    def store_primary_term name, dest = nil
      store_dest dest if dest
      category = uppercase_mb (name.delete_prefix 'fn').chr
      (init_category category).store_term name, dest
    end
  end)

  IndexTermGroup.prepend (::Module.new do
    def <=> other
      this = @name.delete_prefix 'fn'
      that = other.name.delete_prefix 'fn'
      (val = this.casecmp that) == 0 ? this <=> that : val
    end
  end)
end

$ asciidoctor-pdf -r ./index-customizer.rb doc.adoc

By default, Asciidoctor PDF does not optimize the PDF it generates or compress its streams. This section covers several approaches you can take to optimize your PDF.

Enable stream compression

$ asciidoctor-pdf -a compress document.adoc

rghost

$ asciidoctor-pdf -a optimize basic-example.adoc

$ asciidoctor-pdf-optimize basic-example.pdf

The asciidoctor-pdf-optimize is not guaranteed to reduce the size of the PDF file. It may actually make the PDF larger. You should probably only consider using it if the file size of the original PDF is several megabytes.

hexapdf

$ gem install hexapdf

$ hexapdf optimize --compress-pages --force basic-example.pdf basic-example-optimized.pdf

$ hexapdf help optimize

See the contributing guide. To help develop Asciidoctor PDF, or to simply use the development version, refer to the developing and contributing code guide.

• Discussion about image quality in PDFs

Asciidoctor PDF was written by Dan Allen and Sarah White of OpenDevise Inc. on behalf of the Asciidoctor Project.

Copyright © 2014-2020 OpenDevise Inc. and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the LICENSE file. Refer to the NOTICE file for information about third-party Open Source software in use.