Asciidoctor PDF

A PDF converter for AsciiDoc based on web technologies. It allows complex layouts to be defined with CSS and JavaScript, while writing the content in AsciiDoc.

Document - source / PDF

Letter - Source / PDF

Book - source / PDF

Cheat sheet - Source / PDF

Resume - Source / PDF

Slides - Source / PDF

Asciidoctor PDF has support for LaTeX-style mathematical equations (via MathJax) and syntax highlighting (via highlight.js). Many more features can be added by importing an existing JavaScript or CSS framework.

Highlights

• Complex layouts with CSS and JavaScript
• SVG icons with Font Awesome 5
• PDF document outline (i.e., bookmarks)
• Table Of Contents
• Document metadata (title, authors, subject, keywords, etc)
• Fully customizable template
• Syntax highlighting with Highlight.js
• Page numbering
• Preview mode
• STEM support with MathJax 3

Installation

Requirements

You need Node installed on your machine to install and run Asciidoctor PDF. The best way to install Node is to use nvm (Node Version Manager).

How to set up nvm on my machine

Install nvm and Node on Linux or macOS

Follow these installation instructions to set up nvm on your machine.
Once you've installed nvm, open a new terminal and install the latest Node LTS release.

$ nvm install --lts

The above command will install the latest LTS release of Node and automatically set it as your default alias.

Install nvm and Node on Windows

Follow these installation instructions to set up nvm on your machine.
Once you've installed nvm, open an new, regular PowerShell terminal, and install Node using nvm.

$ nvm install 12.13.0
$ nvm use 12.13.0

The above commands will install Node v12.13.0 and enable it.

We recommend using the latest long term support (LTS) release of Node. While you can use other versions of Node, Asciidoctor PDF is only tested against active LTS releases.

Install globally using npm

To install Asciidoctor PDF package globally, open a terminal and type:

$ npm i -g @asciidoctor/core asciidoctor-pdf

NOTE: We recommend installing Asciidoctor PDF globally to make the asciidoctor-pdf command available on your PATH. However, you can also install Asciidoctor PDF in a project directory if you prefer.

Verify that the asciidoctor-pdf command is available on your PATH by running:

$ asciidoctor-pdf --version

NOTE: If you get an error about Executions Policies when running this command on PowerShell, try to use the following command instead: $ asciidoctor-pdf.cmd --version.

If installation was successful, the command should report the version of Asciidoctor PDF.

$ asciidoctor-pdf --version
Asciidoctor PDF 1.0.0-alpha.4 using Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [https://asciidoctor.org]
Runtime Environment (node v10.15.1 on linux)
CLI version 3.0.2

NOTE: If you prefer Yarn over npm, use this command to install the Asciidoctor PDF package:

$ yarn global add @asciidoctor/core asciidoctor-pdf

Install in a project directory (alternative install)

You can opt to install Asciidoctor PDF in a project directory, such as the directory where your AsciiDoc files are stored. To install Asciidoctor PDF in a project directory, move into your project directory and type:

$ npm i @asciidoctor/core asciidoctor-pdf

Dropping the -g flag installs the package under the node_modules folder in the current directory.

Verify that the asciidoctor-pdf command is available by running $(npm bin)/asciidoctor-pdf --version.

Getting started

Asciidoctor PDF provides a standard document layout. To convert an AsciiDoc document using this layout, open a terminal and type:

$ asciidoctor-pdf document.adoc

Configuration

The standard document layout can be configured depending on your needs.

STEM support

To activate equation and formula support, set the stem attribute in the document's header (or by passing the attribute to the command line):

$ asciidoctor-pdf document.adoc -a stem

Title page

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.

$ asciidoctor-pdf document.adoc -a title-page

Additional styles

You can provide a custom stylesheet using the stylesheet attribute. You can also specify where the stylesheet is located with the stylesdir attribute.

$ asciidoctor-pdf document.adoc -a stylesheet=custom.css

Custom layout

It's also possible to create your own layout by extending the default HTML 5 converter. To create a new layout you will need some JavaScript knowledge.

Let's say that we want to override how the document node is converted.

module.exports = {
  document: (node) => `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link href="./layout.css" rel="stylesheet">
</head>
<body>
${node.getContent()}
</body>`,
}

In the above example, we are using Template Literals but you can use your favorite template engine. You can also override other elements.

Complete list of elements

• document
• embedded
• outline
• section
• admonition
• audio
• colist
• dlist
• example
• floating-title
• image
• listing
• literal
• stem
• olist
• open
• page_break
• paragraph
• preamble
• quote
• thematic_break
• sidebar
• table
• toc
• ulist
• verse
• video
• inline_anchor
• inline_break
• inline_button
• inline_callout
• inline_footnote
• inline_image
• inline_indexterm
• inline_kbd
• inline_menu
• inline_quoted

The function takes one parameter, called node. Depending on the context a node can be a Block, a Section, a List. or a Table. Block, Section, List and Table extends AbstractBlock which extends AbstractNode.
If you want to learn more, please read the Asciidoctor.js API documentation.

To help you get started, we provides a few alternative layouts in the examples directory:

Layout	Template file
Letter	examples/letter/template.js
Book	examples/book/template.js
Slides	examples/slides/template.js
Resume	examples/resume/template.js
Cheat sheet (Snyk)	examples/cheat-sheet/snyk/template.js

To enable a custom layout, use the --template-require command line option. For instance, if I want to use the cheat sheet layout on examples/cheat-sheet/maven-security-cheat-sheet.adoc:

$ asciidoctor-pdf ./examples/cheat-sheet/maven-security-cheat-sheet.adoc --template-require ./examples/cheat-sheet/snyk/template.js

It will produce a file named examples/cheat-sheet/maven-security-cheat-sheet.pdf.

How does it work?

Asciidoctor PDF is using an HTML 5 converter to convert an AsciiDoc document to an HTML 5 page. Puppeteer will then run an headless Chrome to generate a PDF from the HTML 5 page.

To paginate content in the browser, we are using Paged.js, an open-source library, that acts as a polyfill for Paged Media and Generated Content for Paged Media W3C specifications.

This project is heavily inspired by ReLaXed.

The file template.js defines how the AsciiDoc content should be converted to HTML 5. Puppeteer will then run an headless Chrome to generate a PDF from the HTML 5 page.

Contribute!

New contributors are always welcome! If you discover errors or omissions in the source code or documentation, please don't hesitate to submit an issue or open a pull request with a fix.