asciidoctor-pdf
:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.
Top Related Projects
:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
CommonMark spec, with reference implementations in C and JavaScript
Blackfriday: a markdown processor for Go
Determines which markup library to use to render a content file (e.g. README) on GitHub
Quick Overview
Asciidoctor PDF is a native PDF converter for AsciiDoc, built with Ruby. It allows users to convert AsciiDoc documents directly to PDF without the need for an intermediate format like DocBook. This project aims to provide a flexible and customizable solution for generating high-quality PDF documents from AsciiDoc source files.
Pros
- Native PDF conversion without intermediate formats
- Highly customizable through themes and extensions
- Supports complex layouts and document structures
- Active development and community support
Cons
- Requires Ruby knowledge for advanced customization
- May have a steeper learning curve compared to simpler PDF converters
- Performance can be slower for very large documents
- Some advanced PDF features may require additional plugins or custom development
Code Examples
- Basic conversion of an AsciiDoc file to PDF:
require 'asciidoctor-pdf'
Asciidoctor.convert_file 'document.adoc', backend: 'pdf', safe: :safe
- Using a custom theme:
Asciidoctor.convert_file 'document.adoc',
backend: 'pdf',
safe: :safe,
attributes: { 'pdf-theme' => 'custom-theme.yml' }
- Converting with custom attributes:
Asciidoctor.convert_file 'document.adoc',
backend: 'pdf',
safe: :safe,
attributes: {
'pdf-fontsdir' => 'fonts',
'source-highlighter' => 'rouge',
'toc' => ''
}
Getting Started
To get started with Asciidoctor PDF, follow these steps:
-
Install the gem:
gem install asciidoctor-pdf -
Create an AsciiDoc file (e.g.,
document.adoc) with your content. -
Convert the file to PDF using the command line:
asciidoctor-pdf document.adoc
Alternatively, you can use Asciidoctor PDF in your Ruby code:
require 'asciidoctor-pdf'
Asciidoctor.convert_file 'document.adoc', backend: 'pdf', safe: :safe
For more advanced usage and customization options, refer to the project's documentation on GitHub.
Competitor Comparisons
:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
Pros of Asciidoctor
- More versatile, supporting multiple output formats (HTML, PDF, EPUB, etc.)
- Larger community and ecosystem with more extensions and integrations
- Better suited for complex documentation projects and book authoring
Cons of Asciidoctor
- Steeper learning curve due to more features and options
- Slower processing speed for large documents compared to Asciidoctor-PDF
- Requires additional setup for PDF output (e.g., using Asciidoctor-PDF as an extension)
Code Comparison
Asciidoctor (Ruby):
require 'asciidoctor'
Asciidoctor.convert_file 'document.adoc', safe: :safe, attributes: {'backend' => 'html5'}
Asciidoctor-PDF:
require 'asciidoctor-pdf'
Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'pdf', attributes: {'pdf-theme' => 'default'}
The main difference is in the backend and attributes specified. Asciidoctor-PDF is specifically tailored for PDF output, while Asciidoctor supports multiple backends.
Both projects share the same core Asciidoctor syntax and processing, but Asciidoctor-PDF focuses on optimizing PDF generation. Asciidoctor is more suitable for general-purpose documentation needs, while Asciidoctor-PDF excels in creating high-quality PDF documents with advanced layout options.
CommonMark spec, with reference implementations in C and JavaScript
Pros of commonmark-spec
- Focuses on standardizing Markdown syntax, providing a clear specification
- Lightweight and easy to implement across various platforms
- Aims to improve compatibility between different Markdown implementations
Cons of commonmark-spec
- Limited to Markdown syntax specification, not a full document processing solution
- Lacks advanced formatting features and output options available in Asciidoctor PDF
- Does not provide direct PDF generation capabilities
Code Comparison
commonmark-spec (example test case):
`foo`
***
`bar`
Asciidoctor PDF (example document structure):
= Document Title
:doctype: book
:pdf-page-size: A4
== Chapter 1
Content goes here.
While commonmark-spec focuses on defining Markdown syntax, Asciidoctor PDF provides a comprehensive solution for generating PDF documents from AsciiDoc markup. The code examples illustrate the difference in focus: commonmark-spec defines how Markdown should be interpreted, while Asciidoctor PDF offers a structured approach to creating complex documents with advanced formatting options.
Blackfriday: a markdown processor for Go
Pros of Blackfriday
- Written in Go, offering better performance and easier integration with Go projects
- Lightweight and focused solely on Markdown parsing
- Supports CommonMark specification
Cons of Blackfriday
- Limited to Markdown input and HTML output
- Lacks advanced document formatting features
- Less active development and community support
Code Comparison
Blackfriday (Go):
import "github.com/russross/blackfriday/v2"
markdown := []byte("# Hello, World!")
html := blackfriday.Run(markdown)
Asciidoctor-pdf (Ruby):
require 'asciidoctor-pdf'
Asciidoctor.convert_file 'document.adoc', backend: 'pdf', safe: :safe
Summary
Blackfriday is a Go-based Markdown parser focused on speed and simplicity, ideal for Go projects requiring Markdown to HTML conversion. Asciidoctor-pdf, on the other hand, is a Ruby-based tool that offers more advanced document formatting capabilities and PDF output, making it suitable for complex documentation needs. While Blackfriday excels in performance and Go integration, Asciidoctor-pdf provides a richer feature set for document processing and output flexibility.
Determines which markup library to use to render a content file (e.g. README) on GitHub
Pros of markup
- Supports multiple markup languages (Markdown, AsciiDoc, Org, etc.)
- Lightweight and easy to integrate into existing projects
- Actively maintained by GitHub, ensuring compatibility with their platform
Cons of markup
- Limited to rendering HTML output
- Less feature-rich compared to specialized converters like asciidoctor-pdf
- May require additional processing for complex document structures
Code Comparison
markup:
GitHub::Markup.render('README.md', File.read('README.md'))
asciidoctor-pdf:
Asciidoctor.convert_file 'document.adoc', backend: 'pdf', safe: :safe
Key Differences
- markup is a general-purpose markup renderer, while asciidoctor-pdf focuses specifically on converting AsciiDoc to PDF
- asciidoctor-pdf offers more advanced formatting and layout options for PDF output
- markup is better suited for quick rendering of various markup formats, while asciidoctor-pdf excels in producing high-quality PDF documents from AsciiDoc sources
Use Cases
- Choose markup for simple HTML rendering of multiple markup formats in web applications
- Opt for asciidoctor-pdf when creating professional-grade PDF documents from AsciiDoc content, especially for technical documentation or books
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
= Asciidoctor PDF: A native PDF converter for AsciiDoc Dan Allen https://github.com/mojavelinux[@mojavelinux]; Sarah White https://github.com/graphitefriction[@graphitefriction] // Settings: :experimental: :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github,env-browser[] :toc: macro :toclevels: 1 endif::[] ifdef::env-github[] :status: :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Aliases: :project-name: Asciidoctor PDF :project-handle: asciidoctor-pdf // URLs: :url-gem: https://rubygems.org/gems/asciidoctor-pdf :url-project: https://github.com/asciidoctor/asciidoctor-pdf :url-project-repo: {url-project} :url-project-issues: {url-project-repo}/issues :url-project-docs: https://docs.asciidoctor.org/pdf-converter/latest :url-prawn: https://prawnpdf.org :url-rvm: https://rvm.io
ifdef::status[] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link=https://asciidoctor.zulipchat.com/] image:{url-project-repo}/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-project-repo}/actions?query=workflow%3ACI+branch%3Amain] image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}] endif::[]
Asciidoctor PDF is a native PDF converter for AsciiDoc that serves the pdf backend.
It bypasses the step of generating an intermediary format such as DocBook, Apache FO, or LaTeX in order to produce PDF.
Instead, you use Asciidoctor PDF to convert your documents directly from AsciiDoc to PDF with Asciidoctor.
The aim of this library is to take the pain out of creating PDF documents from AsciiDoc.
[NOTE]
The documentation for the latest, stable release of Asciidoctor PDF is available at {url-project-docs}/.
If you're looking for the documentation for Asciidoctor PDF 1.6, refer to the {url-project-repo}/tree/v1.6.x#readme[README] in the v1.6.x branch. Asciidoctor PDF 1.6 is no longer being developed and will reach EOL later this year. You are encouraged to migrate to Asciidoctor PDF 2 as soon as possible.
toc::[]
== Overview
Asciidoctor PDF converts an AsciiDoc document directly to a PDF document. The style and layout of the PDF are controlled by a dedicated theme file. To the degree possible, Asciidoctor PDF supports all the features of AsciiDoc that are supported by Asciidoctor. It also provides {url-project-docs}/features/[PDF-specific features]. However, there are {url-project-docs}/features/#limitations[certain limitations] imposed by the PDF format and the PDF library this extension uses.
Asciidoctor PDF uses the Prawn gem and Prawn's extensions, such as prawn-svg and prawn-table, to generate a PDF document. {url-prawn}[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.
TIP: For the latest Asciidoctor PDF features and fixes, see {url-project-docs}/whats-new/[What's New in Asciidoctor PDF].
== Prerequisites
Asciidoctor PDF is built on Asciidoctor. Like Asciidoctor, Asciidoctor PDF is a Ruby application. Therefore, to use it, you'll need a Ruby runtime.
The supported Ruby runtimes are Ruby 2.7 or greater and JRuby 9.2 or greater. However, we always recommend using the most recent release of Ruby or JRuby. All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which will be covered in the <<Install Asciidoctor PDF,next section>>.
To check if you have Ruby available, run the ruby command to print the installed version:
$ ruby -v
Make sure this command reports a Ruby version that starts with 2.7 (or a JRuby version that starts with 9.2). If so, you're ready to proceed. If not, head over to {url-rvm}[rvm.io^] to get RVM and use it to install Ruby.
== Install Asciidoctor PDF
You can install Asciidoctor PDF using the gem install command.
We'll use this command to install the Asciidoctor PDF gem named asciidoctor-pdf that's published on RubyGems.org.
Pass the name of the gem to the gem install command as follows:
$ gem install asciidoctor-pdf
Installing Asciidoctor PDF will install a number of other gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk. For the most part, the versions of these dependencies are locked to the version of Asciidoctor PDF. The patch versions are allowed to vary. Please note that the minimum supported version of the asciidoctor gem (Asciidoctor) is 2.0.10.
For further installation information about installing Asciidoctor PDF, see {url-project-docs}/install/[the installation documentation]. For troubleshooting help, see {url-project-docs}/install/#installation-troubleshooting[Installation troubleshooting].
=== Install a prerelease or development version
To install the latest prerelease of the asciidoctor-pdf gem from RubyGems.org (if a prerelease is available), use the following command:
$ gem install asciidoctor-pdf --pre
You can also {url-project-repo}/blob/main/CONTRIBUTING-CODE.adoc[run the code from source] if you want to use a development version or participate in development.
== Optional dependencies
There are several optional features of this converter that require additional gems to be installed. Those features are as follows.
Source highlighting:: You'll need to {url-project-docs}/syntax-highlighting/[install a syntax highlighter] to use source highlighting (build-time only).
PDF optimization:: If you want to optimize your PDF, you'll need rghost or hexapdf. See {url-project-docs}/optimize-pdf/[Optimize the PDF] for installation and usage instructions.
Automatic hyphenation::
To turn on automatic hyphenation using the hyphens attribute, you'll need to install the text-hyphen gem:
$ gem install text-hyphen
Accelerated image decoding:: Ruby is not particularly fast at decoding images, and the image formats it supports are limited. To help, you can install prawn-gmagick, which delegates the work of decoding images to GraphicsMagick. Refer to {url-project-docs}/image-paths-and-formats/#other-image-formats[Supporting additional image file formats] for instructions about how to enable this integration.
Check the {url-project-docs}/install/#table-minimum-version[minimum supported version table] to make sure you're using a supported version of the dependency.
== Run the Application
Assuming all the required gems install properly, verify you can run the asciidoctor-pdf script:
$ asciidoctor-pdf -v
If you see the version of {project-name} printed, you're ready to use {project-name}!
Let's grab an AsciiDoc document to distill and start putting {project-name} to use.
If you don't already have an AsciiDoc document to work with, you can use the <<examples/basic-example.adoc#,basic-example.adoc>> file found in the examples directory of this project. Copy it to the current directory as follows:
$ cp examples/basic-example.adoc .
Let's take a look at the contents of that file.
ifeval::[{safe-mode-level} >= 20] See <<examples/basic-example.adoc#,basic-example.adoc>>. endif::[] ifeval::[{safe-mode-level} < 20] .basic-example.adoc [source,asciidoc] .... include::examples/basic-example.adoc[] .... endif::[]
It's time to convert the AsciiDoc document directly to PDF.
=== Convert AsciiDoc to PDF
IMPORTANT: You'll need the rouge gem installed to run this example since it uses the source-highlighter attribute with the value of rouge.
Converting to PDF is as straightforward as running the asciidoctor-pdf script using Ruby and passing the AsciiDoc document as the first argument:
$ asciidoctor-pdf basic-example.adoc
This command is a shorter way of running asciidoctor with the PDF converter and backend enabled:
$ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc
The asciidoctor-pdf command saves you from having to remember these low-level options.
That's why we provide it.
When the script completes, you should see the file [.path]basic-example.pdf in the current directory. Asciidoctor creates the output file in the same directory as the input file by default. Open the [.path]basic-example.pdf file with a PDF viewer to see the result.
.Example PDF document rendered in a PDF viewer image::docs/modules/ROOT/images/basic-example-pdf-screenshot.png[Screenshot of PDF document,960,pdfwidth=100%]
For more information about how to use Asciidoctor PDF and PDF-specific AsciiDoc syntax, see the {url-project-docs}/[Asciidoctor PDF documentation].
== Themes
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 {url-project-docs}/theme/[Asciidoctor PDF theming documentation].
ifndef::env-site[] == Contributing
See the <<CONTRIBUTING.adoc#,contributing guide>>. To help develop {project-name}, or to simply use the development version, refer to the <<CONTRIBUTING-CODE.adoc#,developing and contributing code guide>>.
== Authors
{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise Inc. on behalf of the Asciidoctor Project.
== Copyright
Copyright (C) 2014-present 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 link:LICENSE[] file. Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.
Top Related Projects
:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
CommonMark spec, with reference implementations in C and JavaScript
Blackfriday: a markdown processor for Go
Determines which markup library to use to render a content file (e.g. README) on GitHub
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot