Product Overview: Asciidoctor
Asciidoctor is a fast, open-source text processor and publishing toolchain designed to convert documents written in the AsciiDoc format into various output formats. Here’s a detailed look at what Asciidoctor does and its key features.
What Asciidoctor Does
Asciidoctor is the processor that reads AsciiDoc source files and converts them into publishable formats such as HTML 5, DocBook 5, manual pages, PDF, and EPUB 3, among others. This makes it a versatile tool for authors, documentation teams, and anyone needing to generate documentation or content in multiple formats from a single source.
Key Features and Functionality
Conversion Capabilities
Asciidoctor comes with built-in converters for HTML 5, DocBook 5, and manual pages. Additional converters for formats like PDF and EPUB 3 are available through separate gems. This allows users to generate documents in various formats without needing multiple tools.
Customization and Control
Users have 100% control over the output. Asciidoctor supports custom converters and the use of template converters, which allow for the customization of output using Tilt-supported template files. This flexibility ensures that the output can be tailored to specific needs.
Theming and Styling
The PDF converter, in particular, features a composable, configuration-driven theming system similar to basic CSS. This allows for themable AsciiDoc blocks, custom fonts (TTF and limited OTF support), and full SVG support. Users can also configure page size, layout, and document metadata.
Integration with Other Tools
Asciidoctor can be executed in various environments, including Ruby, JVM using AsciidoctorJ, and any JavaScript environment using Asciidoctor.js. This versatility makes it compatible with a wide range of development setups and workflows.
Additional Features
- Syntax Highlighting: Asciidoctor integrates with tools like Rouge, Pygments, or CodeRay for syntax highlighting in code blocks.
- Math and STEM Support: It includes support for MathJax, enabling the rendering of mathematical and scientific content.
- Front and Back Cover Pages: The PDF converter allows for the inclusion of front and back cover pages, title pages, and configurable page backgrounds.
- Internal Cross-Reference Links: Users can create internal cross-reference links within the document.
- Docker Integration: AsciidoctorJ can be used inside a Docker container, managed by Arquillian, to convert AsciiDoc files to HTML and PDF.
AsciiDoc Syntax
Asciidoctor leverages the AsciiDoc format, which is a mature, plain-text document format. AsciiDoc supports various components such as block quotes, source code listings, sidebars, tables, and more. It allows for easy formatting of text, including lead paragraphs, strong and emphasized text, and the use of passthrough macros to include raw content like HTML.
In summary, Asciidoctor is a powerful and flexible tool for converting and publishing content written in AsciiDoc, offering extensive customization options, integration with various environments, and a wide range of output formats. Its robust feature set makes it an ideal choice for documentation and content creation needs.