asciidoctor-pdf v1.0.0-alpha.16

Asciidoctor Web 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.

Asciidoctor Web 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 Web PDF. The best way to install Node is to use nvm (Node Version Manager).

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 Web PDF is only tested against active LTS releases.

Install globally using npm

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

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

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

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

$ asciidoctor-web-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-web-pdf.cmd --version.

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

$ asciidoctor-web-pdf --version
Asciidoctor Web PDF 1.0.0-alpha.10 using Asciidoctor.js 2.2.0 (Asciidoctor 2.0.10) [https://asciidoctor.org]
Runtime Environment (node v12.18.4 on linux)
CLI version 3.4.0

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

$ yarn global add @asciidoctor/core asciidoctor-pdf

Install in a project directory (alternative install)

You can opt to install Asciidoctor Web PDF in a project directory, such as the directory where your AsciiDoc files are stored. To install Asciidoctor Web 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-web-pdf command is available by running $(npm bin)/asciidoctor-web-pdf --version.

Getting started

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

$ asciidoctor-web-pdf document.adoc

IMPORTANT: Asciidoctor Web PDF relies on Puppeteer to generate a PDF from a Web page. If you get the following error, make sure that all the necessary dependencies are installed.

> Unable to generate the PDF - Error: TimeoutError: Timed out after 30000 ms while trying to connect to Chrome!

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-web-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-web-pdf document.adoc -a title-page

Custom styles

You can provide a custom stylesheet using the stylesheet attribute. A custom stylesheet does completely replace the default stylesheet.

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

The stylesheet attribute can accept multiple comma delimited values (without spaces). This can be used to begin with a base stylesheet and then apply supplementary content.

$ asciidoctor-web-pdf document.adoc -a stylesheet="custom.css,override.css"

It's also possible to use the default stylesheet and add custom styles with a custom stylesheet. All default stylesheets are available under the prefix asciidoctor-pdf/css/:

$ asciidoctor-web-pdf document.adoc -a stylesheet="asciidoctor-pdf/css/asciidoctor.css,asciidoctor-pdf/css/document.css,custom.css"

You can also specify where the stylesheets are located with the stylesdir attribute.

$ asciidoctor-web-pdf document.adoc -a stylesdir=css -a stylesheet="custom.css,override.css"

Asciidoctor extensions

Asciidoctor Web PDF can use Asciidoctor extensions written in JavaScript from the CLI. For instance, if you want to use the Asciidoctor Kroki extension, you first need to install it:

$ npm i asciidoctor-kroki

Then, you can use the following command to load this extension:

$ asciidoctor-web-pdf --require asciidoctor-kroki document.adoc

It's also possible to use an extension from a JavaScript file. For instance, if you want to load a local extension declared in a JavaScript file named my-asciidoctor-extension.js, then you can use the following command:

$ asciidoctor-web-pdf --require ./my-asciidoctor-extension.js document.adoc

NOTE: Please note that the extension should export a function named register, otherwise the extension won't be registered:

module.exports.register = function (registry) {
  if (typeof registry.register === 'function') {
    registry.register(function () {
      this.block(function () {
        // ...
      })
    })
  } else if (typeof registry.block === 'function') {
    registry.block(function () {
      // ...
    })
  }
  return registry
}

Diagrams

You can use the Asciidoctor Kroki extension to render diagrams in your PDF. In this example, we create a file named piracy.adoc with the following content:

piracy.adoc

= Piracy

Piracy is an act of robbery or criminal violence by ship upon another ship,
typically with the goal of stealing rum and other valuable items or properties.

Here's what a pirate looks like!

[nomnoml]
....
[Pirate|eyeCount: Int|raid();pillage()|
  [beard]--[parrot]
  [beard]-:>[foul mouth]
]

[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[Pirate]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]
....

Kroki supports more than a dozen diagram libraries. In the above example, we are using the nomnoml UML diagram library.

NOTE: Please note, that you will need to install asciidoctor-kroki, using npm i asciidoctor-kroki.

You can use the following command to generate a PDF:

$ asciidoctor-web-pdf --require asciidoctor-kroki piracy.adoc

Here's the result: piracy.pdf

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.

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:

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-web-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 Web 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.