{"id":13532679,"url":"https://github.com/asciidoctor/asciidoctor-pdf","last_synced_at":"2025-05-12T11:18:13.848Z","repository":{"id":13138008,"uuid":"15820215","full_name":"asciidoctor/asciidoctor-pdf","owner":"asciidoctor","description":":page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.","archived":false,"fork":false,"pushed_at":"2025-05-05T22:50:48.000Z","size":31643,"stargazers_count":1172,"open_issues_count":13,"forks_count":500,"subscribers_count":57,"default_branch":"main","last_synced_at":"2025-05-07T15:50:58.327Z","etag":null,"topics":["asciidoc","asciidoctor","converter","pdf","pdf-generation","prawn","ruby"],"latest_commit_sha":null,"homepage":"https://docs.asciidoctor.org/pdf-converter/latest/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asciidoctor.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":"CONTRIBUTING-CODE.adoc","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-01-11T09:48:11.000Z","updated_at":"2025-05-05T22:50:51.000Z","dependencies_parsed_at":"2023-11-12T09:04:07.468Z","dependency_job_id":"53a5788a-9297-4c42-8f52-d16328adcce1","html_url":"https://github.com/asciidoctor/asciidoctor-pdf","commit_stats":{"total_commits":4783,"total_committers":94,"mean_commits":50.88297872340426,"dds":"0.042860129625757915","last_synced_commit":"daeafdde601c87e644c9ed28091672b48cc80c40"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-pdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-pdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-pdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-pdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asciidoctor","download_url":"https://codeload.github.com/asciidoctor/asciidoctor-pdf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253066588,"owners_count":21848451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","asciidoctor","converter","pdf","pdf-generation","prawn","ruby"],"created_at":"2024-08-01T07:01:12.825Z","updated_at":"2025-05-11T11:11:11.886Z","avatar_url":"https://github.com/asciidoctor.png","language":"Ruby","funding_links":[],"categories":["Ruby","Awesome Ruby CLIs"],"sub_categories":["Converting"],"readme":"= Asciidoctor PDF: A native PDF converter for AsciiDoc\nDan Allen \u003chttps://github.com/mojavelinux[@mojavelinux]\u003e; Sarah White \u003chttps://github.com/graphitefriction[@graphitefriction]\u003e\n// Settings:\n:experimental:\n:idprefix:\n:idseparator: -\nifndef::env-github[:icons: font]\nifdef::env-github,env-browser[]\n:toc: macro\n:toclevels: 1\nendif::[]\nifdef::env-github[]\n:status:\n:!toc-title:\n:caution-caption: :fire:\n:important-caption: :exclamation:\n:note-caption: :paperclip:\n:tip-caption: :bulb:\n:warning-caption: :warning:\nendif::[]\n// Aliases:\n:project-name: Asciidoctor PDF\n:project-handle: asciidoctor-pdf\n// URLs:\n:url-gem: https://rubygems.org/gems/asciidoctor-pdf\n:url-project: https://github.com/asciidoctor/asciidoctor-pdf\n:url-project-repo: {url-project}\n:url-project-issues: {url-project-repo}/issues\n:url-project-docs: https://docs.asciidoctor.org/pdf-converter/latest\n:url-prawn: https://prawnpdf.org\n:url-rvm: https://rvm.io\n\nifdef::status[]\nimage:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link=https://asciidoctor.zulipchat.com/]\nimage:{url-project-repo}/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-project-repo}/actions?query=workflow%3ACI+branch%3Amain]\nimage:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}]\nendif::[]\n\nAsciidoctor PDF is a native PDF converter for AsciiDoc that serves the `pdf` backend.\nIt bypasses the step of generating an intermediary format such as DocBook, Apache FO, or LaTeX in order to produce PDF.\nInstead, you use Asciidoctor PDF to convert your documents directly from AsciiDoc to PDF with Asciidoctor.\nThe aim of this library is to take the pain out of creating PDF documents from AsciiDoc.\n\n[NOTE]\n====\nThe documentation for the latest, stable release of Asciidoctor PDF is available at {url-project-docs}/.\n\nIf you're looking for the documentation for Asciidoctor PDF 1.6, refer to the {url-project-repo}/tree/v1.6.x#readme[README] in the v1.6.x branch.\nAsciidoctor PDF 1.6 is no longer being developed and will reach EOL later this year.\nYou are encouraged to migrate to Asciidoctor PDF 2 as soon as possible.\n====\n\ntoc::[]\n\n== Overview\n\nAsciidoctor PDF converts an AsciiDoc document directly to a PDF document.\nThe style and layout of the PDF are controlled by a dedicated theme file.\nTo the degree possible, Asciidoctor PDF supports all the features of AsciiDoc that are supported by Asciidoctor.\nIt also provides {url-project-docs}/features/[PDF-specific features].\nHowever, there are {url-project-docs}/features/#limitations[certain limitations] imposed by the PDF format and the PDF library this extension uses.\n\nAsciidoctor PDF uses the Prawn gem and Prawn's extensions, such as prawn-svg and prawn-table, to generate a PDF document.\n{url-prawn}[Prawn] is a general purpose PDF generator for Ruby that features high-level APIs for common needs like setting up the page and inserting images and low-level APIs for positioning and rendering text and graphics.\n\nTIP: For the latest Asciidoctor PDF features and fixes, see {url-project-docs}/whats-new/[What's New in Asciidoctor PDF].\n\n== Prerequisites\n\nAsciidoctor PDF is built on Asciidoctor.\nLike Asciidoctor, Asciidoctor PDF is a Ruby application.\nTherefore, to use it, you'll need a Ruby runtime.\n\nThe supported Ruby runtimes are Ruby 2.7 or greater and JRuby 9.2 or greater.\nHowever, we always recommend using the most recent release of Ruby or JRuby.\nAll required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which will be covered in the \u003c\u003cInstall Asciidoctor PDF,next section\u003e\u003e.\n\nTo check if you have Ruby available, run the `ruby` command to print the installed version:\n\n $ ruby -v\n\nMake sure this command reports a Ruby version that starts with 2.7 (or a JRuby version that starts with 9.2).\nIf so, you're ready to proceed.\nIf not, head over to {url-rvm}[rvm.io^] to get RVM and use it to install Ruby.\n\n== Install Asciidoctor PDF\n\nYou can install Asciidoctor PDF using the `gem install` command.\nWe'll use this command to install the Asciidoctor PDF gem named *asciidoctor-pdf* that's published on RubyGems.org.\nPass the name of the gem to the `gem install` command as follows:\n\n $ gem install asciidoctor-pdf\n\nInstalling Asciidoctor PDF will install a number of other gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk.\nFor the most part, the versions of these dependencies are locked to the version of Asciidoctor PDF.\nThe patch versions are allowed to vary.\nPlease note that the minimum supported version of the asciidoctor gem (Asciidoctor) is 2.0.10.\n\nFor further installation information about installing Asciidoctor PDF, see {url-project-docs}/install/[the installation documentation].\nFor troubleshooting help, see {url-project-docs}/install/#installation-troubleshooting[Installation troubleshooting].\n\n=== Install a prerelease or development version\n\nTo install the latest prerelease of the *asciidoctor-pdf* gem from RubyGems.org (if a prerelease is available), use the following command:\n\n $ gem install asciidoctor-pdf --pre\n\nYou can also {url-project-repo}/blob/main/CONTRIBUTING-CODE.adoc[run the code from source] if you want to use a development version or participate in development.\n\n== Optional dependencies\n\nThere are several optional features of this converter that require additional gems to be installed.\nThose features are as follows.\n\nSource highlighting::\nYou'll need to {url-project-docs}/syntax-highlighting/[install a syntax highlighter] to use source highlighting (build-time only).\n\nPDF optimization::\nIf you want to optimize your PDF, you'll need rghost or hexapdf.\nSee {url-project-docs}/optimize-pdf/[Optimize the PDF] for installation and usage instructions.\n\nAutomatic hyphenation::\nTo turn on automatic hyphenation using the `hyphens` attribute, you'll need to install the `text-hyphen` gem:\n\n $ gem install text-hyphen\n\nAccelerated image decoding::\nRuby is not particularly fast at decoding images, and the image formats it supports are limited.\nTo help, you can install prawn-gmagick, which delegates the work of decoding images to GraphicsMagick.\nRefer to {url-project-docs}/image-paths-and-formats/#other-image-formats[Supporting additional image file formats] for instructions about how to enable this integration.\n\nCheck the {url-project-docs}/install/#table-minimum-version[minimum supported version table] to make sure you're using a supported version of the dependency.\n\n== Run the Application\n\nAssuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:\n\n $ asciidoctor-pdf -v\n\nIf you see the version of {project-name} printed, you're ready to use {project-name}!\n\nLet's grab an AsciiDoc document to distill and start putting {project-name} to use.\n\nIf you don't already have an AsciiDoc document to work with, you can use the \u003c\u003cexamples/basic-example.adoc#,basic-example.adoc\u003e\u003e file found in the _examples_ directory of this project.\nCopy it to the current directory as follows:\n\n $ cp examples/basic-example.adoc .\n\nLet's take a look at the contents of that file.\n\nifeval::[{safe-mode-level} \u003e= 20]\nSee \u003c\u003cexamples/basic-example.adoc#,basic-example.adoc\u003e\u003e.\nendif::[]\nifeval::[{safe-mode-level} \u003c 20]\n.basic-example.adoc\n[source,asciidoc]\n....\ninclude::examples/basic-example.adoc[]\n....\nendif::[]\n\nIt's time to convert the AsciiDoc document directly to PDF.\n\n=== Convert AsciiDoc to PDF\n\nIMPORTANT: You'll need the `rouge` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `rouge`.\n\nConverting to PDF is as straightforward as running the `asciidoctor-pdf` script using Ruby and passing the AsciiDoc document as the first argument:\n\n $ asciidoctor-pdf basic-example.adoc\n\nThis command is a shorter way of running `asciidoctor` with the PDF converter and backend enabled:\n\n $ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc\n\nThe `asciidoctor-pdf` command saves you from having to remember these low-level options.\nThat's why we provide it.\n\nWhen the script completes, you should see the file [.path]_basic-example.pdf_ in the current directory.\nAsciidoctor creates the output file in the same directory as the input file by default.\nOpen the [.path]_basic-example.pdf_ file with a PDF viewer to see the result.\n\n.Example PDF document rendered in a PDF viewer\nimage::docs/modules/ROOT/images/basic-example-pdf-screenshot.png[Screenshot of PDF document,960,pdfwidth=100%]\n\nFor more information about how to use Asciidoctor PDF and PDF-specific AsciiDoc syntax, see the {url-project-docs}/[Asciidoctor PDF documentation].\n\n== Themes\n\nThe layout and styling of the PDF is driven by a YAML configuration file.\nTo learn how the theming system works and how to create and apply custom themes, refer to the {url-project-docs}/theme/[Asciidoctor PDF theming documentation].\n\nifndef::env-site[]\n== Contributing\n\nSee the \u003c\u003cCONTRIBUTING.adoc#,contributing guide\u003e\u003e.\nTo help develop {project-name}, or to simply use the development version, refer to the \u003c\u003cCONTRIBUTING-CODE.adoc#,developing and contributing code guide\u003e\u003e.\n\n== Authors\n\n{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise Inc. on behalf of the Asciidoctor Project.\n\n== Copyright\n\nCopyright (C) 2014-present OpenDevise Inc. and the Asciidoctor Project.\nFree use of this software is granted under the terms of the MIT License.\n\nFor the full text of the license, see the link:LICENSE[] file.\nRefer to the \u003c\u003cNOTICE.adoc#,NOTICE\u003e\u003e file for information about third-party Open Source software in use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciidoctor%2Fasciidoctor-pdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasciidoctor%2Fasciidoctor-pdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciidoctor%2Fasciidoctor-pdf/lists"}