Exporting AsciiDoc to PDF: A Step-by-Step Guide for Every OS

This guide covers multiple workflows on macOS, iOS, Windows, and Linux for converting AsciiDoc files to PDF. We’ll detail installation of required tools and step-by-step usage for each platform. We’ll also discuss advanced toolchains for those needing extra customization (e.g. LaTeX output). The guide assumes basic terminal knowledge but no AsciiDoc expertise.

macOS and iOS: Using adoc Studio (App for AsciiDoc)

adoc Studio is an all-in-one AsciiDoc editor for Mac, iPad, and iPhone that can quickly export PDFs without manual installation of toolchains. It provides a live preview and uses a unified CSS-based styling for HTML and PDF outputs.

• Opening AsciiDoc Files: Launch adoc Studio and open your .adoc file (or create a new document). The interface splits into an editor (left) and preview (right) so you can see formatted output in real-time as you write.

• Switching to PDF Preview: By default, the preview might show HTML output. To switch to a PDF preview, click the eye icon (Preview toggle) in the top toolbar and choose “PDF” from the format dropdown. See the screenshot below for the preview format selector. This renders your document as it will appear in PDF form.

• Exporting to PDF: Once you are satisfied with the preview, export the PDF. On Mac, use File → Export → PDFor click the Share/Export button in the toolbar and choose PDF. On iPad/iPhone, tap the export/share icon and select “Export as PDF” (you can also use the iOS “Share” menu to save the PDF to Files or send it). This generates a PDF of your document with the current styling.

• Setting Export Preferences: In adoc Studio, export options are tied to Product Styles. You can manage these via File → Export → Products... or via the shortcut ^ ⌘ E. Here you can select a style (theme) for your PDF output (e.g. “Asciidoctor” style or a custom one you create). Each style is essentially a set of CSS files defining the appearance in both HTML and PDF outputs. You can duplicate an existing style and customize it to create your own look.

• Customizing Styles with CSS: A unique feature of adoc Studio is that it uses CSS for PDF design, thanks to a built-in Vivliostyle engine (a CSS Paged Media renderer). The same CSS file can style both HTML and PDF; you add media queries to target PDF specifically. For example, in your style’s CSS you might include:

@media vivliostyle {     
    @page {         
        size: A4 portrait;         
        margin: 2cm;     
    }     

    /* add further PDF-specific rules */ 
}

This @media vivliostyle block applies only to PDF output in adoc Studio. Through CSS you can adjust fonts, colors, margins, or even hide/show certain elements in the PDF. adoc Studio provides a default CSS theme (“Standard”) that you can tweak – e.g., you might change the heading fonts or add a company logo on the title page by modifying the CSS.

• AsciiDoc Attributes for PDF: You can also control PDF structure using standard AsciiDoc attributes, no coding needed. For instance, set :title-page: to include a dedicated title page, :front-cover-image: to add a cover image, and :pagenums: to enable/disable page numbers. These attributes (when placed at the top of your .adoc document or in Document Settings) will be honored by adoc Studio’s PDF generator. Footnotes and endnotes are supported as well – footnotes will appear at the bottom of each page by default (you can change this with :footnotes-position:).

adoc Studio

Create Technical Documentation in AsciiDoc.
Organize, Write and Share.
Documentation in AsciiDoc.
Organize, Write and Share.

Start Free 14-Day Trial

macOS: Using Homebrew + Asciidoctor PDF (Command Line)

If you prefer a command-line workflow or need automation, you can use the Asciidoctor PDF toolchain on macOS. This involves installing Ruby and the Asciidoctor PDF gem. Homebrew (the macOS package manager) makes this easier by providing Ruby and Asciidoctor packages.

• Install Homebrew: If you don’t have Homebrew, install it first. Run the official one-line installer in Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

(Visit brew.sh for instructions.)

• Install Asciidoctor (Ruby): Homebrew can install Ruby and the Asciidoctor gem in one go. In Terminal, run:

brew install asciidoctor

Homebrew does not install its own Ruby any more; it relies on the system Ruby. Homebrew brings the formula asciidoctor and depends on Apple’s system Ruby (or Homebrew’s ruby formula if the user has installed it). You can verify by running asciidoctor -v (which prints the version). However, note: the Homebrew package includes the core Asciidoctor (for HTML and DocBook) but not the PDF converter gem by default. We’ll install that next.

• Install the Asciidoctor PDF Gem: Asciidoctor PDF is a Ruby gem (asciidoctor-pdf) that extends Asciidoctor for PDF output. To install it, run:

gem install asciidoctor-pdf

(You might not need sudo if using Homebrew’s Ruby, as it installs gems in an isolated location.) This fetches all necessary Ruby libraries (like Prawn for PDF generation). If you plan to use syntax highlighting in code blocks, also install the Rouge gem: gem install rouge (Rouge is a pure-Ruby highlighter that Asciidoctor PDF will use by default).

• Generating a PDF: Navigate to your AsciiDoc document’s folder in Terminal. Run the Asciidoctor PDF command on your file:

asciidoctor-pdf myDocument.adoc

This will produce myDocument.pdf in the same directory. The asciidoctor-pdf command is now on your PATH after gem installation. If you get an error about the command not found, ensure Ruby’s gem bin directory is in your PATH. You can also run which asciidoctor-pdf to confirm its location. By default, the PDF will use Asciidoctor PDF’s standard styling.

• Customizing PDF Output (Themes): Asciidoctor PDF (the Ruby tool) uses a theme file (YAML format) to control the PDF look (fonts, colors, margins, etc.). You can create a custom theme to match your desired style. Start by obtaining the default theme as a baseline: run asciidoctor-pdf --theme=default -D . -a pdf-theme=default -a pdf-themesdir=. dummy.adoc (there’s also an official command to generate the default YAML). This will output a default-theme.yml which contains all settings. Edit this YAML to customize (for example, change the base font family, header background color, etc.). Then, to use your theme, run:

asciidoctor-pdf -a pdf-theme=./my-custom-theme.yml myDocument.adoc

You can also specify -a pdf-themesdir=<directory> if your theme file is in a separate folder.

Additionally, standard AsciiDoc attributes are supported by Asciidoctor PDF: e.g. :doctype: book (to format as a book with chapters), :toc: for table of contents, :pagenums: for page numbers, :title-page: for an automatic title page, and :front-cover-image: to add a cover image. Set these in your document header as needed.

However, these scripts quickly expand in size. For the documentation on Merlin Project, our project management software, our scripts looked like this:

After installation, you could automate PDF generation with a Makefile or a simple script. For instance:

#!/bin/bash asciidoctor-pdf -a toc -a pagenums -a pdf-theme=./company-theme.yml "$1"

This converts an AsciiDoc file ($1) to PDF with a TOC and page numbers using a custom theme.

Windows Workflows

On Windows, you have several options to convert AsciiDoc to PDF:

Windows: Using WSL (Windows Subsystem for Linux)

WSL allows you to run a Linux environment on Windows 10/11, which is very handy for using Linux tools like Asciidoctor. The idea is to install a lightweight Linux (like Ubuntu) and use the Linux Asciidoctor inside it.

• Enable WSL: On Windows 10 or 11, open PowerShell as Administrator and run:

wsl --install

This command enables the Windows Subsystem for Linux and installs Ubuntu by default. (If you prefer, you can also enable WSL via “Turn Windows features on or off” and then install a Linux distro from the Microsoft Store, but the one-liner above is simplest.)

• Initial WSL Setup: Restart if prompted. Then, launch the “Ubuntu” app that was installed (from the Start menu). It will finalize setup and ask you to create a UNIX username and password.

• Install Asciidoctor in WSL: Now you have a Ubuntu bash shell. Update package lists and install Asciidoctor and its PDF components. In the WSL terminal, run:

sudo apt update
sudo apt install asciidoctor ruby-asciidoctor-pdf -y

This uses Ubuntu’s package manager to install Asciidoctor and Asciidoctor-PDF Ruby gems system-wide. (On recent Ubuntu releases, this will give you Asciidoctor PDF 1.5 or 2.x depending on the distro. If the packaged version is outdated, you can alternatively install via Ruby gems as described in the Linux section below.)

• Generate PDF in WSL: Navigate to your AsciiDoc files. Note that your Windows drives are accessible under /mnt/c/ (for C: drive, etc.) in WSL. For example, if your document is at C:\Docs\file.adoc, in WSL it will be /mnt/c/Docs/file.adoc. Run the conversion:

asciidoctor-pdf /mnt/c/Docs/file.adoc

This will create file.pdf in the same folder (you’ll see it appear back in Windows Explorer under C:\Docs\). You can open the PDF in Windows as usual.

Tip: You can edit the AsciiDoc using your favorite Windows editor (VS Code, Notepad++, etc.) and just use WSL for the conversion command. Or you can edit within WSL using editors like vim or nano if you prefer command-line editing.

Windows: Installing Ruby and Asciidoctor-PDF Natively (Using Mise)

If WSL isn’t an option or you prefer native Windows tools, you can install Ruby on Windows and run Asciidoctor PDF directly. Historically, one would use RubyInstaller for Windows. A modern approach is to use Mise-en-place (Mise), a tool version manager, to easily install Ruby and manage tools.

• Install Mise: Mise is a multi-language environment manager by JDX (it replaces tools like RVM, rbenv, etc., on Windows). The recommended way on Windows is via Scoop or Winget (Windows package managers). For example, to install via Windows Winget, open PowerShell and run:

winget install jdx.mise

This will install Mise on your system and add it to your PATH. If Winget isn’t available, you can use Scoop (scoop install mise) or download the binary manually.

• Set Up Mise for Ruby: After installing Mise, you need to “activate” it in your shell. For PowerShell, add the following to your PowerShell profile (as admin):

This ensures Mise is available in each new shell. Restart PowerShell to load Mise.

echo 'mise activate pwsh | Out-String | Invoke-Expression' >> $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1

• Install Ruby via Mise: With Mise, installing Ruby is straightforward. Run:

mise use -g ruby@latest

This command tells Mise to download and install the latest Ruby 3.2.x (or specify another version if needed) and set it as the global default Ruby. Mise will handle fetching and compiling Ruby (using ruby-build under the hood). It may take a few minutes as it builds Ruby and any required MSYS2 tools.

• Verify Ruby: Once done, check ruby -v. You should see a Ruby version (e.g. 3.2.x) output, indicating Ruby is installed and on PATH (Mise shims it into PATH).

• Install Asciidoctor PDF Gem: Now use Ruby’s gem to install Asciidoctor and the PDF converter. Run:

gem install asciidoctor asciidoctor-pdf

This installs the Asciidoctor CLI and the PDF converter gem into your Ruby environment. (With Mise, gems are installed to your user directory by default, and the executables should be shimmed to PATH as well.)

• Run the Conversion: Use asciidoctor-pdf just as on other platforms:

asciidoctor-pdf C:\Docs\myDocument.adoc

The first time you run this, it may set up any needed dependencies (e.g., it might download PDF themes or fonts if needed, but typically the gem has what it needs). This generates myDocument.pdf. By default on Windows, the output will be in the same directory as the input file.

• Customization: The usage of Asciidoctor PDF on Windows is the same as on macOS/Linux. Use attributes or custom theme files as described earlier to tweak the output. For instance, you can have a theme YAML and specify -a pdf-theme=... in the command.

• Alternative – RubyInstaller: If you prefer not to use Mise, you can install RubyInstaller for Windows which provides a Ruby+DevKit in an installer. After installing RubyInstaller, open its DevKit/MSYS2 environment and use gem install asciidoctor-pdf similarly. This achieves the same end result (Ruby and gems on Windows). However, tools like Mise or Scoop streamline the process and environment management.

Web-based: Using AsciiDocLive (Online Converter)

If you cannot install anything (or prefer a quick online solution), AsciiDocLive is a web-based AsciiDoc editor and converter. It’s essentially AsciiDoc in the browser.

• What it is: AsciiDocLive (accessible at asciidoclive.com or via Docswriter) provides an online editor where you paste or write AsciiDoc, and it shows a live preview (HTML). It’s free to use and requires no signup for basic functionality.

• How to use AsciiDocLive: Open the website and you’ll see a text editor on the left and a preview on the right. Paste your .adoc content into the left pane. The right pane will display the formatted document (usually in HTML form). There is an option to switch the output format or export. AsciiDocLive primarily focuses on HTML preview, but you can get a PDF with a workaround:

  1. Export to HTML: Use the site’s Save/Export function to download the HTML version of your document.

  2. Convert HTML to PDF: Once you have the HTML file, you can convert it to PDF. An easy way is to open that HTML in a web browser and print to PDF (all modern browsers support “Save as PDF” in the print dialog). Alternatively, use an online HTML-to-PDF service or a tool like wkhtmltopdf. The Stack Overflow community suggests this two-step approach for AsciiDocLive users, since AsciiDocLive itself doesn’t directly provide a PDF download.

Linux Workflows

On Linux, AsciiDoc to PDF conversion is typically done via Asciidoctor (Ruby) or the older a2x toolchain. We’ll cover three methods: the native Asciidoctor PDF gem, the DocBook/FOP method, and the newer web-based PDF generator.

Linux: Using Asciidoctor PDF (Ruby Gem on Linux)

Most Linux distros include Asciidoctor in their repositories, making installation straightforward.

• Install Prerequisites: Ensure you have Ruby installed. On Debian/Ubuntu, install via apt: sudo apt-get install -y ruby-full (or use the default Ruby that comes with the OS).

• Note: sudo apt install asciidoctor ruby‑asciidoctor‑pdf is only available from Ubuntu 24.04 “Noble” onward. It fails on 22.04 LTS or Debian 12 (no ruby‑asciidoctor‑pdf package).

You’ll also want the Asciidoctor tools:

sudo apt-get install -y asciidoctor ruby-asciidoctor-pdf

On Debian-based systems, this installs the Asciidoctor CLI and the asciidoctor-pdf gem packaged for system Ruby. Fedora/CentOS users can use dnf install asciidoctor (and if available, rubygem-asciidoctor-pdf). Arch Linux has asciidoctor in pacman. These packages might lag behind the latest release, so if you need cutting-edge features, consider the gem method below.

• Alternative Gem Install: If your distro’s Asciidoctor is outdated or you prefer not to use system packages, you can install via gem. This is similar to macOS: install Ruby (via package manager or a version manager like rbenv), then gem install asciidoctor-pdf. For example, on Ubuntu:

sudo apt-get install -y ruby-full build-essential zlib1g-dev 
gem install asciidoctor asciidoctor-pdf gem install rouge

(We include build tools in case native extensions are needed; Rouge for syntax highlighting.)

• Conversion: Run asciidoctor-pdf file.adoc just as on other platforms. This creates file.pdf. By default, Asciidoctor PDF will use a built-in theme that looks decent (sans-serif font for body, blue headings). If you want to change the look, use a custom theme file as described earlier (pass -a pdf-theme=...).

• Customization: The same attributes and theme YAML apply on Linux. If you installed via apt, the command might be available as asciidoctor-pdf immediately. If you used gem without adding to PATH, you might need to run it via bundle exec or add Ruby’s bin to PATH.

• Example: Suppose you have multiple .adoc files (chapters) and you want to combine them into one PDF. Asciidoctor can include other files using the include:: directive in AsciiDoc.

Asciidoctor PDF can take multiple inputs and concatenate them (treating them as one document, which they will be if each one has a level-0 title).

• Linux-specific tip: You can integrate this with make. For instance, a simple Makefile:

all: mydoc.pdf

mydoc.pdf: *.adoc
    asciidoctor-pdf -r asciidoctor-diagram -a toc -a pdf-theme=theme.yml main.adoc -o mydoc.pdf

This would regenerate the PDF whenever any .adoc source changes, including processing diagrams via the asciidoctor-diagram extension.

Linux: Using asciidoctor-fopub (DocBook XSL-FO Toolchain)

Asciidoctor-FoPub is an alternative route that uses the DocBook toolchain (XSL-FO with Apache FOP) to produce PDFs. It’s essentially the spiritual successor to the old a2x from AsciiDoc.py. This method is useful if you need the power of DocBook’s styling or if you want to leverage print-oriented XSL customizations. It’s a bit more complex but very flexible.

• Install Java: FoPub requires Java (the FOP processor is a Java program). Ensure you have a JDK installed (OpenJDK 8 or newer). On Ubuntu: sudo apt install default-jdk -y. Verify with java -version.

• Get asciidoctor-fopub: This tool is available on GitHub: asciidoctor/asciidoctor-fopub. You can clone the repository or download a release if available. For simplicity, do:

git clone https://github.com/asciidoctor/asciidoctor-fopub.git cd asciidoctor-fopub ./gradlew clean assemble

This will build the fopub tool. (It may download dependencies like FOP and DocBook XSL on first run.)

• Alternatively, there might be a pre-built distribution: after building, you’ll have a build/dist folder with fopubscripts. You can copy that wherever convenient or add to PATH.

• Using FoPub: The FoPub tool expects DocBook XML as input. So first, convert your AsciiDoc to DocBook. Use Asciidoctor for that:

asciidoctor -b docbook -o temp.xml myDocument.adoc

This creates temp.xml (DocBook 5 format) from your AsciiDoc. Now run FoPub on the XML:

./fopub temp.xml

This will generate temp.pdf using FOP with the default DocBook XSL styles. All needed resources (XSL files, fonts, etc.) are managed internally by FoPub – the first run downloads the DocBook XSL and sets up everything, so subsequent runs work offline. The output PDF will have the DocBook default styling (which is fairly plain but very functional, with proper headers/footers, etc.).

• Customization: One big advantage of this approach is extensive configurability via XSL-FO. You can tweak the DocBook XSL stylesheets to alter the PDF output. For example, you could change the font family, page size, or how chapter titles appear by editing an XSL file. Asciidoctor-fopub allows you to provide a custom XSL directory with the -t option. The GitHub README describes copying the docbook-xsl folder from fopub into your project and modifying it. For instance, you could enable the “Colony” theme (a predefined DocBook style) by toggling it in common.xsl. You can also create your own XSL layer to, say, remove chapter numbers or change the way admonitions look. Because this uses Apache FOP, you have access to fine-grained PDF features (like PDF bookmarks, accessibility tags, etc., which the FOP tool supports well).

• Example custom change: If you don’t want section numbers in the PDF, you might try setting the AsciiDoc attribute :sectnums!: – but as one user found, FOP might still number them. In such a case, you’d adjust the DocBook XSL (for example, override the template that adds section numbers, or use an XSL param to disable numbering). This highlights that the FOP route sometimes requires digging into DocBook XSL intricacies for advanced changes.

The Tools in Direct Comparison

* Not included automatically: only true after the user adds gem install asciidoctor‑diagram