Narcoleptic Programmers' Medicine

    asciidoctor-pdf

    1.0.0-alpha.12 • Public • Published

    Asciidoctor Web PDF

    Build npm version

    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 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

    Running from pre-compiled binaries

    Asciidoctor Web PDF is available for each release as a zip file for Windows 64-bit, Linux 64-bit and macOS 64-bit (x86-64).

    Go to the releases page and download the appropriate binary for your platform. Extract this to a folder of your choosing.

    From a command line in this folder you can then run the asciidoctor-web-pdf command.

    Running from Source

    To run from source, 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).

    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 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"
    

    TIP: You can also provide a custom stylesheet in addition to all the default styles using the + prefix:

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

    Notice the + before custom.css, it means that the stylesheet will be included after all the default styles. This is particularly useful when you want to override a few styles.

    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"
    

    Front cover image

    When using a title page (see above), you might want to set a front cover image. To do that, you will need to add a few lines of CSS.

    Here's a complete example:

    1. Create a file named orly.adoc with the following content:
    = Hoping This Works
    :doctype: book
    
    == Guessing
    
    The first step is guessing.
    

    We are using :doctype: book to get a title page.

    1. Create a file named orly.css with the following content:
    @page :first {
      background-size: contain;
      background-image: url("./orly.jpg");
    }
    
    /* move the book title to the correct location */
    #cover > h1 {
      color: white;
      margin-top: 8cm;
      font-size: 7rem;
    }
    1. Download the image orly.jpg and put it next to the orly.adoc file.

    2. Open a terminal and type:

      $ asciidoctor-web-pdf orly.adoc -a stylesheet="+orly.css"

    The above command will create a file named orly.pdf which should look like:

    front-cover-image

    Docinfo

    You can add custom content to the head, header or footer of the output document using docinfo files. Docinfo files are useful for injecting auxiliary metadata, stylesheet, and script information into the output not added by the converter.

    In addition, you can add running content to the output document. Running content can then be positioned via CSS on the top, bottom, left or right margins of pages. This can come in handy when you want to repeat complex elements (address, contact...) on all pages for documents like invoices or reports. If you want to learn more about running elements, please read the following section Running elements.

    IMPORTANT: You will need to declare running elements as running content via CSS. Otherwise, running elements will be visible on the page.

    To enable docinfo files, you need to configure the scope using the docinfo attribute. The scope defines if the docinfo files apply for a specific document ("private") or for all documents in the same directory ("shared").

    Mode Location Behavior Docinfo file name
    Private Head Adds content to <head> for <docname>.adoc files. <docname>-docinfo-pdf.html
    Private Header Adds content to start of document for <docname>.adoc files. <docname>-docinfo-header-pdf.html
    Private Footer Adds content to end of document for <docname>.adoc files. <docname>-docinfo-footer-pdf.html
    Private Running Adds running content to start of document for <docname>.adoc files. <docname>-docinfo-running-pdf.html
    Shared Head Adds content to <head> for any document in same directory. docinfo-pdf.html
    Shared Header Adds content to start of document for any document in same directory. docinfo-header-pdf.html
    Shared Footer Adds content to end of document for any document in same directory. docinfo-footer-pdf.html
    Shared Running Adds running content to start for any document in same directory. docinfo-running-pdf.html

    To specify which file(s) you want to apply, set the docinfo attribute to any combination of these values:

    • private-head
    • private-header
    • private-footer
    • private-running
    • private (alias for private-head,private-header,private-footer,private-running)
    • shared-head
    • shared-header
    • shared-footer
    • shared-running
    • shared (alias for shared-head,shared-header,shared-footer,shared-running)

    Setting docinfo with no value is equivalent to setting the value to private.

    For example:

    :docinfo: shared,private-footer
    

    This docinfo configuration will apply the shared docinfo head, header, running and footer files, if they exist, as well as the private footer file, if it exists.

    Running elements

    Running elements can be positioned on the top, bottom, left or right margins of pages. Let's take a concrete example where we want to display an address block in the bottom left box of every page.

    <address class="contact-us">
      <strong>Example Inc.</strong><br>
      1234 Example Street<br>
      Antartica, Example 0987<br>
      <abbr title="Phone">P:</abbr> (123) 456-7890
    </address>

    First, you will to define your element as running using the position property. Here, we are using runningContact as an identifier, but you can use any name that makes sense to you:

    .contact-us {
      position: running(runningContact)
    }

    Then, place the element into a margin box with the element() function via the content property:

    @page {
      @bottom-left {
        content: element(runningContact)
      }
    }

    As you can see, we are using the identifier runningContact defined earlier. The above definition will effectively remove the .contact-us element from the page and repeat it on every page in the bottom left box.

    Here's a complete example:

    1. Create a file named report.adoc with the following content:
    = 2021 Annual Report
    :docinfo: private
    
    1. Create a file named report-docinfo-running-pdf.html with the following content:
    <address class="contact-us">
      <strong>Handicap International</strong><br>
      138, avenue des Frères Lumière<br>
      69008 Lyon - France
    </address>
    1. Create a file named report.css with the following content:
    .contact-us {
      width: 6cm;
      position: running(runningContact)
    }
    
    @page {
      margin: 1cm 2cm 4cm 2cm;
    }
    
    @page :right {
      @bottom-left {
        content: element(runningContact)
      }
    
      @bottom-right {
        content: counter(page);
        margin: 10pt 10pt 30pt 0;
      }
    }
    
    @page :left {
      @bottom-right {
        content: element(runningContact)
      }
    
      @bottom-left {
        content: counter(page);
        margin: 10pt 0 30pt 10pt;
      }
    }
    1. Open a terminal and type:

      $ asciidoctor-web-pdf report.adoc -a stylesheet="+report.css"

    The above command will create a file named report.pdf which should look like:

    complex-footer

    TIP: Please note that, in this case, you don't need to use a docinfo file, you can declare the "contact us" block directly in the AsciiDoc file. In other words, you should get the same result if you are using the following content:

    = 2021 Annual Report
    
    [.contact-us]
    --
    *Handicap International* +
    138, avenue des Frères Lumière +
    69008 Lyon - France
    --
    

    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.

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

    Keywords

    none

    Install

    npm i asciidoctor-pdf

    DownloadsWeekly Downloads

    633

    Version

    1.0.0-alpha.12

    License

    MIT

    Unpacked Size

    2.64 MB

    Total Files

    20

    Last publish

    Collaborators

    • ggrossetie