Export as PDF

The extension provides a command to export the current AsciiDoc file as PDF.

Open the command palette — Ctrl+Shift+P or F1 (Mac: Cmd+Shift+P).
Select AsciiDoc: Export document as PDF.
Choose the folder and filename for the generated PDF.

Output location

By default, exporting a document opens a save dialog so you can choose the folder and filename. The suggested name is the document file name with a .pdf extension, in the same directory as the document.

Two settings let you control this behaviour — useful, for example, to repeatedly regenerate the same PDF in a tight iteration cycle.

asciidoc.pdf.askOutputLocation (default true): When set to false, the export skips the save dialog and writes the PDF directly, overwriting any existing file without prompting.
asciidoc.pdf.outputDirectory (default empty): Directory where the PDF is written. When empty, the PDF is saved next to the document. The exported file always keeps the document name with a .pdf extension.

The output directory is resolved as follows:

an empty value writes the PDF next to the document (the historical behaviour);
an absolute path (for example /home/me/exports or C:\exports) is used as-is;
a relative path (for example build/pdf) is resolved against the workspace folder, or against the document’s own directory when the file does not belong to any workspace;
the ${workspaceFolder} variable is expanded to the workspace folder path, so ${workspaceFolder}/build/pdf is equivalent to build/pdf.

The directory is created automatically if it does not exist.

For a quick save-and-regenerate workflow, set both options, for example in .vscode/settings.json:

{
  "asciidoc.pdf.askOutputLocation": false,
  "asciidoc.pdf.outputDirectory": "${workspaceFolder}/build/pdf"
}

Each export then overwrites build/pdf/<document-name>.pdf without any prompt.

Because these settings have a resource scope, they can be configured per workspace folder.

PDF engine

By default, PDF export relies on asciidoctor-pdf.

To use wkhtmltopdf instead, set asciidoc.pdf.engine to wkhtmltopdf, and configure asciidoc.pdf.wkhtmltopdfCommandPath if needed.

See the PDF settings for all related options.

Custom PDF theme

A custom PDF theme applies to the asciidoctor-pdf engine only — it has no effect on the preview, which is HTML styled with CSS (see Preview → Styling).

The recommended way is to declare the asciidoctor-pdf theme attributes in the document header:

= My Document
:pdf-themesdir: ../themes
:pdf-theme: custom

This resolves the custom-theme.yml file (the -theme.yml suffix is added automatically) from the themes directory next to the document. The extension runs asciidoctor-pdf with --base-dir set to the document’s directory, so relative paths such as ../themes are resolved from there.

Keeping the configuration in the document header rather than in the extension settings makes it portable across machines and across documents that use different themes or folder structures.

Alternatively, you can pass the same attributes through the asciidoc.pdf.asciidoctorPdfCommandArgs setting — see the PDF settings.

Troubleshooting

`asciidoctor-pdf` is not found (or the export fails after a while)

When exporting, you may see a notification that asciidoctor-pdf was not found on your PATH, or an error such as command failed: asciidoctor-pdf or the more cryptic spawn /bin/sh ENOENT.

There are two distinct causes:

asciidoctor-pdf is not installed: Install it by following the Asciidoctor PDF installation guide. If Bundler is available, the extension can also install a local copy for you on first use, in its global storage directory.
asciidoctor-pdf is installed but not visible to VS Code: This is the most common cause on macOS, and it explains the puzzling behaviour where the export works right after a fresh start but fails "after some time", and only a full restart of VS Code (closing every window is not enough) fixes it.

When VS Code is launched from the Dock, Finder or Spotlight — rather than from a terminal with code . — it does not inherit your shell PATH. Tools installed by a Ruby version manager or a package manager (Homebrew, rbenv, rvm, asdf, gem install, …) live in directories that your shell adds to PATH through its profile files (.zprofile, .zshrc, .bash_profile, …). Those directories are therefore missing from the environment VS Code passes to asciidoctor-pdf, so the executable cannot be found even though it runs fine in a terminal.

The misleading spawn /bin/sh ENOENT is a long-standing Node.js quirk: when a child process is spawned with a working directory that does not exist, the error is reported against the shell binary rather than the directory. In practice it means the extension tried to run the bundled fallback copy of asciidoctor-pdf from a directory that had not been created yet — a side effect of asciidoctor-pdf not being found on the PATH in the first place.

The extension already appends the usual install locations (/opt/homebrew/bin, /usr/local/bin, rbenv/rvm/gem bin directories) to the PATH it uses to run asciidoctor-pdf. If your installation lives somewhere else, use one of the following remedies:

Set the full path to the executable in the asciidoc.pdf.asciidoctorPdfCommandPath setting (see the PDF settings), for instance /opt/homebrew/bin/asciidoctor-pdf. You can find it by running which asciidoctor-pdf in a terminal.
Or launch VS Code from a terminal with code . so it inherits your shell PATH.