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

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.

Install

You need Node.js installed on your machine to install and run Asciidoctor PDF. To install Asciidoctor PDF, open a terminal and type:

$ npm i -g asciidoctor 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

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

$ asciidoctor-pdf --version
Asciidoctor PDF 1.0.0-alpha.3 using Asciidoctor.js 2.0.0 (Asciidoctor 2.0.6) [https://asciidoctor.org]
Runtime Environment (node v10.15.1 on linux)
CLI version 3.0.1

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

NOTE: The default stylesheet will still be applied. While it's possible to override existing rules, the goal is to provide additional styles for custom roles, for instance:

Please edit the [.path]_package.json_ file.

.path {
  color: #fecbcb;
}

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.

About

Convert AsciiDoc documents to PDF using web technologies

https://asciidoctor.org

MIT License

Languages

Language:CSS 60.4%Language:JavaScript 39.6%