AsciiDoc to PDF: Convert .adoc Files With Asciidoctor PDF or Your Browser
Three ways to turn an .adoc file into a PDF, from the Asciidoctor PDF command line to an HTML detour for machines without Ruby.

The direct way to convert AsciiDoc to PDF is Asciidoctor PDF: install it with gem install asciidoctor-pdf and run asciidoctor-pdf your-document.adoc. If you can't install Ruby, use Asciidoctor's Docker image, or convert the .adoc file to HTML with Asciidoctor.js and turn that HTML into a PDF in your browser or with an online HTML to PDF converter.
Which way fits depends on how often you do it. A one-off manual for a colleague needs a different setup than a docs repository that should build its PDF on every commit.
What an .adoc File Is
An .adoc file is plain text written in AsciiDoc, a lightweight markup language for technical documentation. It looks a bit like Markdown (which our Markdown to PDF converter reads directly), but it has tables, cross-references, admonitions and includes built in.
Since it's plain text, it lives well in Git, and that's why many software projects write their manuals in it. Readers outside the team usually don't have an AsciiDoc viewer, though, so a PDF is the easy format to hand them.
Method 1: Convert AsciiDoc to PDF With Asciidoctor PDF
Asciidoctor PDF is the Asciidoctor project's own PDF converter. It reads the .adoc file directly and writes the PDF, with no browser or LaTeX in between.
Install Ruby and Asciidoctor PDF
Asciidoctor PDF is a Ruby gem, so you need Ruby first (version 2.7 or later, says its install page). On Windows, Asciidoctor's docs name RubyInstaller or Chocolatey. This video walks through the installation:
Then open a terminal and install the gem, which brings Asciidoctor along with it:
gem install asciidoctor-pdf
Run the Conversion
- Open a terminal in the folder that holds your .adoc file.
- Run
asciidoctor-pdf your-document.adoc. - Open
your-document.pdf, which appears in the same folder.
If images are missing from the PDF, the paths are the usual cause. Image paths are resolved against the imagesdir attribute, so set it in the document header (for example :imagesdir: images) or run the command from the folder the paths assume.
Change Fonts, Colors and Layout With a Theme
Asciidoctor PDF reads a theme file in YAML that controls the style and layout. The file has to end in .yml, not .yaml. Going by its docs, this command loads resources/themes/basic-theme.yml:
asciidoctor-pdf -a pdf-theme=basic -a pdf-themesdir=resources/themes your-document.adoc
Why Do Chinese or Other Letters Come Out as Boxes?
The fonts the default theme bundles cover only part of Unicode, so Chinese and other scripts need another font. You don't have to write a theme to get one: Asciidoctor PDF ships a built-in theme with font fallbacks that its docs say covers a broad range of Chinese, Japanese and Korean. We didn't run it, since Asciidoctor isn't on our test setup, but these are the attributes those docs give:
asciidoctor-pdf -a pdf-theme=default-with-font-fallbacks -a scripts=cjk -a text-align=left your-document.adoc
Here scripts=cjk adds line break points between those characters, and text-align=left turns off justified text. To see which characters a font lacks, add -v. For wider coverage or other scripts, your own theme has to point to a TrueType or OpenType font that has them.
No Ruby? Use Asciidoctor's Docker Image
No Ruby on your machine, or no permission to install it? Docker is the shortest way out if you have it: Asciidoctor's image includes Asciidoctor PDF. From a macOS or Linux shell, run docker run -it -u $(id -u):$(id -g) -v <your folder>:/documents/ asciidoctor/docker-asciidoctor, then asciidoctor-pdf your-document.adoc inside it.
Method 2: Convert AsciiDoc to HTML, Then HTML to PDF
Without Ruby or Docker, go through HTML with Asciidoctor.js, which needs Node.js instead of Ruby: run npm i -g asciidoctor, and then asciidoctor your-document.adoc makes your-document.html.
- Convert the .adoc file to HTML. Add
-a data-urito the command so the images are packed into the HTML file itself. - Open the HTML file in Chrome, Edge, Firefox or Safari.
- Press Ctrl+P (Cmd+P on a Mac) and choose Save as PDF as the destination.
You can also upload the HTML file to our HTML to PDF converter. It renders the file in a headless Chromium browser, keeps the text selectable and the links clickable, and makes A4 pages with a 20 pixel margin. We tried it in November 2026 with a 572 B test page and got a 39.0 KB, one-page PDF back.

Only the HTML file gets uploaded, so images linked by a relative path stay behind. That's why the data-uri attribute matters: with it, the pictures travel inside the file. Our ASPX to PDF guide runs into the same catch with saved web pages.
Method 3: Batch-Convert AsciiDoc to PDF From the Command Line
A folder full of .adoc files takes one loop in a macOS or Linux shell:
for file in *.adoc; do
asciidoctor-pdf "$file"
done
Try the command on one file before you run it on the whole folder. In a CI pipeline (GitHub Actions, GitLab CI and the like), the same command runs after each commit, so the PDF never falls behind the source.
For a folder of Word or other Office files, our guide to converting many files to PDF at once has the LibreOffice command.
When You Only Need the Source as a PDF
Sometimes nobody needs the formatted manual: a reviewer wants to read and annotate the raw .adoc text. Rename the file from .adoc to .txt and convert it with our TXT to PDF tool, which keeps the markup exactly as written.

Combine, Shrink and Protect the Finished PDF
A finished manual often has more parts than the .adoc file. A cover page written in Word goes through Word to PDF, and Merge PDF puts the cover and the converted manual into one file.
PDFs with many screenshots get big. If the file is too large to email, run it through Compress PDF, and add a password with Protect PDF if the manual is internal.
Frequently Asked Questions about AsciiDoc to PDF
How do I convert AsciiDoc to PDF without losing formatting?
Use Asciidoctor PDF, which reads AsciiDoc directly. The HTML detour depends on the stylesheet and images being inside the HTML file.
Can I convert an .adoc file to PDF online?
There's no direct .adoc upload on pdf-file.com. Convert the file to HTML first, then upload the HTML to our HTML to PDF converter, or print it to PDF in your browser.
Why are images missing from my AsciiDoc PDF?
The image paths don't resolve. Set the imagesdir attribute to the folder your images are in, or run the command from the folder the paths are relative to.
Does Asciidoctor PDF work on Windows, Mac and Linux?
Yes. It needs Ruby 2.7 or later on any of them, and the gem and asciidoctor-pdf commands are the same.



