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.
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.1Asciidoctor PDF provides a standard document layout. To convert an AsciiDoc document using this layout, open a terminal and type:
$ asciidoctor-pdf document.adoc
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
bookdoctype. - The
title-pageattribute 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;
}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. Here's the complete list:
documentembeddedoutlinesectionadmonitionaudiocolistdlistexamplefloating-titleimagelistingliteralstemolistopenpage_breakparagraphpreamblequotethematic_breaksidebartabletoculistversevideoinline_anchorinline_breakinline_buttoninline_calloutinline_footnoteinline_imageinline_indexterminline_kbdinline_menuinline_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.
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.
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.
![@dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
