The Complete Guide To AsciiDoc in 2024
Get to know AsciiDoc, a powerful yet easy-to-use markup language. Learn how to create, manage, and publish documents with ease.
What is AsciiDoc?
AsciiDoc is a lightweight, human-readable markup language. It's designed to simplify the writing of technical documents, books, blogs, and even slides.
AsciiDoc was created in 2002 by Stuart Rackham, a software developer who recognized the need for a lightweight, plain-text markup language that could be easily converted into various output formats, such as HTML, PDF, and DocBook. By focusing on structure and content rather than formatting, AsciiDoc empowers writers to craft well-structured documents without the need for complex formatting tools.
You write an AsciiDoc document the same way you would write a normal text document. There are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats.
Here’s an example to demonstrate formatting in AsciiDoc:
Why Should You Use AsciiDoc?
AsciiDoc belongs to a class of markup languages that are "lightweight" because they aim to provide a minimalistic and easy-to-read approach to text formatting. Examples of similar languages include Markdown and reStructuredText. What distinguishes AsciiDoc is its ability to handle complex content structures while remaining easy to learn and use. To make it concrete: In direct comparison with Markdown and LaTeX, it requires the least amount of characters for simple syntax elements.
While Markdown is a more widely-known markup language, AsciiDoc offers several advantages when it comes to more complex writing tasks:
Standardized: AsciiDoc is moving toward standardization, with the Eclipse Foundation’s AsciiDoc Working Group leading the effort. Other markup languages like Markdown lack such a universal standard.
Human readable, flexible Syntax: AsciiDoc uses minimal tags for markup, making content easy to distinguish from formatting instructions in the editor. It also offers more formatting options. For example, while Markdown uses the same syntax for links and images, AsciiDoc provides different methods based on the desired output.
Many built-in Features: AsciiDoc is a fully-featured markup language without dialects. In contrast, Markdown requires extensions for features like tables, footnotes, or citations, which exist only in dialects like MultiMarkdown. The issue: Extending Markdown syntax can lead to compatibility issues if others don’t have the same add-ons installed.
Various Output Formats: If you need to publish your content in different formats (HTML, PDF, etc.), AsciiDoc provides a seamless way to do this with minimal reformatting. Some apps even allow you to use a single stylesheet for all formats.
Versioning and Automation: AsciiDoc integrates seamlessly with Docs-as-Code workflows, making it ideal for teams using version control systems like Git and CI/CD pipelines. Its compatibility with Git and other tools makes it perfect for projects with multiple contributors to the same documentation.
The problem with Markdown [...] - ‘flavours’, non-standardisation, etc., make its apparent simplicity an illusion. Once Asciidoc has a finalised standard it will be even more compelling.
When Should You Use AsciiDoc?
AsciiDoc is widely used for technical documentation, making it ideal for creating software guides, API manuals, and code documentation. Its structured format helps organize complex information clearly. Developers and technical writers prefer AsciiDoc for its ability to manage detailed content efficiently.
Another common use of AsciiDoc is in writing books and e-books, especially on technical or academic subjects. Authors find its straightforward syntax allows them to focus on content creation, producing professional-quality output without getting bogged down in formatting. Also, users tend to AsciiDoc for blogs and websites as well as slides and presentations. As you can see, the use cases are endless.
The Philosophy Behind AsciiDoc
AsciiDoc embodies a philosophy that emphasizes simplicity, readability, and efficiency in content creation.
Docs-as-Code: AsciiDoc fits the Docs-as-Code approach of treating documentation like a software code. Therefore, AsciiDoc files can be integrated seamlessly with version control systems like Git.
Readability and Maintainability: AsciiDoc’s syntax is easy to read and maintain, making it ideal for long-term projects and easy onboarding of new contributors.
Flexibility and Extensibility: AsciiDoc is flexible and extensible, allowing custom macros and integration with various tools, making it adaptable to diverse documentation needs.
Community-Driven: AsciiDoc thrives on community contributions, ensuring continuous development and relevance through collaborative efforts.
AsciiDoc versus Word, Google Docs & Co.
Now you might be wondering: Why should we learn all these fancy tags when we can simply click on a button or press a shortcut? To put it differently: Why don't we stick with MS Word or Google Docs?
MS Word and Google Docs, among others, are What You See Is What You Get (WYSIWYG) editors. WYSIWYG editors allow users to see the final output as they write, applying styles, formatting, and visual elements directly. They are great for shorter texts, but as soon as documents scale, there are several limitations.
WYSIWYG editors limit content reuse across platforms and formats. Their tight integration of content and presentation makes adapting to outputs like HTML or PDF challenging without manual adjustments. In contrast, markup languages enable single-source publishing, where a master document generates multiple outputs with different formats and styles — something WYSIWYG editors can’t handle efficiently.
Moreover, WYSIWYG editors struggle with version control. The “Docs as Code” approach, which treats documents like code, relies on tools like Git. Markup languages like AsciiDoc produce plain text files, ideal for version control, whereas WYSIWYG-generated files, treated as binary, restrict this functionality.
Lastly, markup languages allow dynamic integration of external files, keeping documents updated. WYSIWYG editors, by contrast, often require manual updates, making content management more tedious.
Getting Started with AsciiDoc
AsciiDoc is particularly strong when it comes to organizing content in a structured way. You can create large, complex documents by breaking them down into smaller sections or chapters, which can be included and managed separately. Let's explore some of the key elements of AsciiDoc:
Document Title and Metadata: Each AsciiDoc document typically starts with a title and optional metadata, which help define the document's structure and appearance.
Document Title: The title is defined at the very top using a single equals sign (
=).Metadata: Metadata such as author, revision number, and date can be added below the title.
Basic Syntax and Structure
Headings: Headings in AsciiDoc are created using the equals sign (=). The number of equals signs corresponds to the level of the heading:
= Level 1 Heading== Level 2 Heading=== Level 3 Heading
Bonus: Here are 10 Tips to improve your headings.
Paragraphs: Paragraphs are simply lines of text separated by a blank line. There’s no special syntax needed to define a paragraph. Highlight certain words through formatting. For this, either set the tags yourself, or use the common shortcuts (⌘+B for bold text).
Lists: AsciiDoc supports several types of lists, including unordered, ordered, and description lists.
Unordered List: Use an asterisk (
*) or hyphen (-) to create unordered list items.Ordered List: Use a period (
.) after a number to create ordered list items.Description List: Use double colons (
::) after the term being described.
Links: Links in AsciiDoc can be created using a straightforward syntax.
Hyperlinks:
http://example.com[Link Text]Internal References:
<<anchor-id,Link Text>>
Images: Including images in AsciiDoc is simple, using the image:: macro. If you adjust the image, it is automatically updated in the document, provided the same name remains.
Advanced Syntax and Features
Tables: AsciiDoc supports the creation of tables, both simple and complex.
Simple Table: Use the pipe character (
|) to separate columns.Complex Table: Use additional formatting options for styling and spanning.
Macros: AsciiDoc allows for the inclusion of various macros to handle dynamic content, external file inclusion, and more. The best part: You keep the original file in it's place and only reference it. Therefore, no copies are needed and all updates will be visible in your document.
Includes:
include::filename.adoc[]
Attribute: You can define and reuse attributes throughout your document, which is useful for managing repeated content.
Attribute Definition:
:attribute_name: valueAttribute Reference:
{attribute_name}-> The preview and export will display the text from the definition (in this case "value")
Besides their use as a variable, Attributes allow you to customize your document further. For example by adding page numbers to the pdf output, or by inserting a table of contents.
But that's just the tip of the iceberg. AsciiDoc offers a wide range of features like admonitions, footnotes or conditions to embed or exclude text in the export. Explore our learning path for a quick introduction to these key elements.
Using AsciiDoc with CSS Stylesheets
One of the strengths of AsciiDoc is its ability to be styled with CSS, especially when generating HTML output. This allows for a high degree of customization in how your documents appear.
Custom Styles: You can link to a custom CSS file when converting AsciiDoc to HTML, allowing you to apply your own styles.
Theme Files: Asciidoctor supports theme files that can control the styling of PDFs and other formats.
It’s important to distinguish between AsciiDoc converters. For example, Asciidoctor uses different template languages for PDF and HTML. While HTML relies on CSS, AsciidoctorPDF requires a separate tool for PDF conversion. In contrast, tools like adoc Studio use CSS for both HTML and PDF, allowing you to maintain a single stylesheet for all exports.
Tools and Plugins for AsciiDoc
When it comes to working with AsciiDoc, choosing the right tool can make a significant difference in your productivity and the quality of your output. Two primary categories of tools are available: Integrated Development Environments (IDEs) and dedicated AsciiDoc editors like adoc Studio.
adoc Studio
With adoc Studio, you work on your texts anytime and anywhere. Write, edit, proofread, and publish your work as PDF and HTML without the hassle of using a terminal.
It provides a user-friendly environment that makes working with AsciiDoc more accessible to everyone, from beginners to advanced users. The software is available for Mac, iPad & iPhone.
Advantages of using adoc Studio
AsciiDoc without the Terminal: In adoc Studio, you write your text in the editor and see it instantly displayed in the preview to the right. Our custom parser ensures the preview always reflects the current HTML or PDF document. Other converters such as Asciidoctor require command line commands and complex scripts.
Same CSS Stylesheet for HTML and PDF: Use ready-made templates or your own CSS styles for the design—whether HTML or PDF—with a single stylesheet for all outputs. Other converters, like Asciidoctor, require different template languages for various formats, such as Asciidoctor for HTML and AsciidoctorPDF for PDF.
Intuitive User Interface: Designed for usability, adoc Studio features a clean, intuitive interface that simplifies the learning curve compared to traditional AsciiDoc tools. To further enhance ease of use, we’ve build adoc Coach, a syntax completion menu that suggests and explains syntax directly at your cursor.
Asciidoctor
Asciidoctor is an implementation of the AsciiDoc language. It’s a fast, open-source toolchain that processes AsciiDoc files and converts them into formats like HTML, PDF, and ePub.
While it offers powerful features, such as IDE integration and plugin support, Asciidoctor doesn’t have a native application and must be run through the terminal which can be daunting for non-developers.
Using IDEs for AsciiDoc
IDEs provide developers with comprehensive tools for writing, editing, testing, and debugging code in one place. Features like syntax highlighting, code completion, and debugging tools make IDEs highly versatile for software development. Many popular IDEs, including Visual Studio Code, IntelliJ IDEA, and Atom, support AsciiDoc through plugins and extensions, allowing seamless integration with Asciidoctor. However, there are also some downsides of using IDEs and SSGs instead of a native app.
To use Asciidoctor within Visual Studio Code, follow these steps:
1. Install AsciiDoc Extension:
Open Visual Studio Code and navigate to the Extensions Marketplace.
Search for “AsciiDoc” and install the AsciiDoc by Asciidoctor extension.
2. Preview AsciiDoc Files:
Open any .adoc file in the editor. With the extension installed, VS Code will automatically render a live preview in a split window.
You can toggle the preview using the command palette (Ctrl+Shift+P) and selecting AsciiDoc: Toggle Preview.
3. Export AsciiDoc to HTML or PDF:
After writing your AsciiDoc content, use the Asciidoctor CLI to convert the file into your desired format. For example, to convert to HTML, open a terminal within VS Code and run:
asciidoctor mydocument.adoc
To convert to PDF, you need a second command:
asciidoctor-pdf mydocument.adoc
As your project grows in complexity, the scripts required to export documents into multiple formats—such as HTML and PDF—tend to become longer and more intricate. Managing different styles, layouts, and media assets across formats increases the need for more elaborate scripts.
For example, when working on our Merlin Project documentation, we had to create and run a more complex script to ensure proper formatting across both HTML and PDF outputs. This script handled conditional text, custom stylesheets, and embedded resources, ensuring consistency and quality across formats.
Resources and Further Reading
This should be enough for a broad overview into AsciiDoc. However, if you are hungry for more, here's a list of resources with further information.
Video Tutorials: Explore our AsciiDoc learning path in adoc Studio. Through easy-to-follow chapters, you’ll master document creation in AsciiDoc. You can also follow us on YouTube for more tutorial videos.
Syntax References, Q&A Sites and Community Forums:
If you want to know why we decided to develop our own AsciiDoc writing environment, check out our Making Of.
Final Thoughts:
AsciiDoc’s flexibility and power make it indispensable for content creators, especially in technical fields. Its ability to generate high-quality, multi-format documents from a single source ensures consistent, polished content across platforms with minimal effort. Templates and style sheets, for example, ensure this.
Whether you’re a solo developer, technical writer, or part of a large team, AsciiDoc provides the tools to succeed. By applying the strategies in this guide, you can confidently create, manage, and publish your content with efficiency.
As you integrate AsciiDoc into your workflow, you’ll find that its simplicity, paired with its robust capabilities, offers a complete solution for modern documentation needs.
