What is AsciiDoc?

The ultimate guide to getting started with AsciiDoc by Chris Chinchilla

AsciiDoc is a lightweight, human-readable markup language. It was created in 2002 by Stuart Rackham, a software developer, to simplify the writing of technical documents, books, blogs, and even slides. AsciiDoc focuses on structure and content rather than formatting, empowering 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.
Stuart Rackham, Creator of AsciiDoc

Here’s an example to demonstrate formatting in AsciiDoc:

Example of AsciiDoc markup syntax and rendered output

When Should You Use AsciiDoc?

Common use cases for AsciiDoc including docs, books, and blogs

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. Companies like Red Hat, the Eclipse Foundation, and many open-source projects rely on AsciiDoc for their official documentation.

Another common use of AsciiDoc is in writing books and e-books, especially on technical or academic subjects. Try our book template or scientific paper template to get started. Publishers like O'Reilly Media accept AsciiDoc as an authoring format. Authors find its straightforward syntax allows them to focus on content creation, producing professional-quality output without getting bogged down in formatting.

AsciiDoc is also a popular choice for blogs and websites. Through the website export in adoc Studio, or static site generators like Antora and Jekyll, you can create navigable web pages from AsciiDoc documents. These tools enable content teams to build documentation portals directly from AsciiDoc files. Additionally, AsciiDoc works well for slides and presentations — tools like Asciidoctor Reveal.js let you create presentation slides from plain text. As you can see, the use cases are broad and varied.

Benefits of AsciiDoc

Key benefits of AsciiDoc over other markup languages
  • 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 Philosophy Behind AsciiDoc

AsciiDoc embodies a philosophy that emphasizes simplicity, readability, and efficiency in content creation.

Core philosophy behind AsciiDoc including Docs-as-Code and readability
  • Docs-as-Code: AsciiDoc fits the Docs-as-Code approach of treating documentation like 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.

Your First AsciiDoc Document

Before diving into the syntax details, let’s create a complete AsciiDoc document from scratch. This gives you a feel for how AsciiDoc works in practice. Create a new file called my-first-document.adoc and paste the following content:

:toc:
:icons: font

= My First AsciiDoc Document
John Doe <john@example.com>
v1.0, 2026-01-15

== Introduction

AsciiDoc supports _italic_, *bold*, and `monospace` text.

== Key Features

The markup language makes writing structured documents easy:

* Simple syntax for everyday formatting
* Built-in support for tables and lists
* Multiple output formats from a single source

// This line is a comment. It is invisible in the output.

=== A Simple Table

|===
| Feature | Supported

| Bold text
| Yes

| Tables
| Yes

| Footnotes
| Yes
|===

== Conclusion

That's it! You've written your first AsciiDoc document.
Visit our https://www.adoc-studio.app/blog[blog] for more tips.

This short document already demonstrates several core concepts: a document header with title, author, and version; attributes like :toc: for an automatic table of contents; text formatting; a list; a table; and a link. Open it in adoc Studio or process it with Asciidoctor, and you’ll see a fully formatted document with a clickable table of contents.

Notice how the source file is easy to read even without rendering. That’s one of the key design principles of AsciiDoc: the plain text is meaningful on its own, while the rendered output adds visual polish. You don’t need any special software to read or write AsciiDoc — any text editor works. But a dedicated tool like adoc Studio gives you the best experience with live preview and syntax assistance.

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

Overview of basic AsciiDoc syntax elements

Headings

Headings in AsciiDoc are created using the equals sign (=). The number of equals signs corresponds to the level of the heading:

= Document Title (Level 0)
== Section Title (Level 1)
=== Subsection (Level 2)
==== Sub-Subsection (Level 3)

This renders a clear document hierarchy, similar to <h1> through <h4> in HTML. Note that the document title (=) should only appear once at the very top of your file.

Bonus: Here are 10 Tips to improve your headings.

Paragraphs and Text Formatting

Paragraphs are simply lines of text separated by a blank line. There’s no special syntax needed to define a paragraph. AsciiDoc provides rich formatting options:

This is *bold* text.
This is _italic_ text.
This is `monospace` text.
This is *_bold and italic_* text.
This is #highlighted# text.
This is ^super^script and ~sub~script.

You can also use the common shortcuts in adoc Studio — for example, ⌘+B for bold text.

Lists

AsciiDoc supports several types of lists. Here are practical examples for each:

Unordered List — use asterisks (*) for nesting:

* Item 1
* Item 2
** Nested item 2a
** Nested item 2b
* Item 3

Ordered List — use dots (.) for automatic numbering:

. First step
. Second step
.. Sub-step a
.. Sub-step b
. Third step

Description List — use double colons (::) to pair a term with its definition:

AsciiDoc:: A lightweight markup language.
Markdown:: Another popular markup language.

Checklist — use [*] for checked and [ ] for unchecked items:

* [*] Write the introduction
* [*] Add code examples
* [ ] Review and publish

Links

Links in AsciiDoc can be created using a straightforward syntax:

https://example.com[Visit Example]
link:document.pdf[Download the PDF]
<<section-title,Jump to Section>>
mailto:info@example.com[Send Email]
  • Hyperlinks: External URLs are auto-detected, or use the link: macro for local files.
  • Internal References: Use <<anchor-id,Link Text>> to link within your document.

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.

image::screenshot.png[Screenshot of the app, 600]

The first value in brackets is the alt text, followed by the optional width. For more details, check out our best practices for images in AsciiDoc. You can also use the inline variant image:icon.png[] (single colon) to place an image within a line of text.

Basic AsciiDoc syntax examples for headings, lists, and links

Advanced Syntax and Features

Tables

AsciiDoc supports the creation of tables, both simple and complex:

|===
| Name | Role | Language

| Alice
| Developer
| Java

| Bob
| Designer
| CSS
|===

For more control, you can specify column widths and alignment. Use cols="1,2,3" for proportional widths, and <, >, or ^ for left, right, or center alignment.

Macros and Includes

AsciiDoc allows for the inclusion of external files, keeping the original file in its place. No copies are needed and all updates will be visible in your document:

= My Manual
include::chapters/introduction.adoc[]
include::chapters/getting-started.adoc[]
include::shared/glossary.adoc[]

You can also include only specific lines or tagged regions from a file, which is useful for embedding code snippets from actual source files. Read our guide on mastering the include directive for advanced techniques. Also explore includes in our learning path.

include::src/main.py[lines=5..15]
include::src/app.js[tag=setup]

Attributes

You can define and reuse attributes throughout your document, which is useful for managing repeated content:

:product-name: adoc Studio
:version: 4.0
:homepage: https://www.adoc-studio.app

Download {product-name} {version} from {homepage}.

Besides their use as variables, attributes allow you to customize your document further. For example by adding page numbers to the PDF output (:pagenums:), inserting a table of contents (:toc:), or enabling syntax highlighting (:source-highlighter: highlight.js).

Guide for choosing the right AsciiDoc syntax element

Admonitions

Admonitions are visual callout blocks that highlight important information. AsciiDoc supports five types:

NOTE: This is a general note for the reader.

TIP: A helpful tip to improve your workflow.

WARNING: Be careful with this step.

IMPORTANT: Do not skip this configuration.

CAUTION: This action cannot be undone.

Each type renders with a distinct icon and color, making it easy for readers to spot critical information at a glance. For technical documentation, see our guide on warning labels and safety notices, or try our ISO-ready admonition styles.

Source Code Blocks

AsciiDoc provides powerful syntax highlighting for code blocks. Specify the language after the opening delimiter:

[source,python]
----

def greet(name):
    return f"Hello, {name}!"

print(greet("World"))
----

You can also add callouts to explain specific lines in your code:

[source,java]
----

public class Main {
    public static void main(String[] args) { // <1>
        System.out.println("Hello!"); // <2>
    }
}
----

<1> Entry point of the application
<2> Prints a greeting to the console

Callouts (the numbered markers <1>, <2>) are a unique AsciiDoc feature that lets you annotate code line by line — something Markdown simply cannot do.

Footnotes

Footnotes allow you to add supplementary information without breaking the reading flow:

AsciiDoc was created in 2002.footnote:[By Stuart Rackham, a software developer from New Zealand.]

The footnote text appears at the bottom of the page, automatically numbered. This is especially useful for academic writing and technical references.

Cross-References and Anchors

AsciiDoc lets you create anchors and reference them from anywhere in your document:

[[my-section]]
== My Section

Refer to <<my-section>> for more details.

Section titles automatically generate anchors based on their text, so you can reference them directly with <<section-title>>. For longer documents, this feature is invaluable for navigation.

But that’s just the tip of the iceberg. AsciiDoc offers even more features like conditional directives to include or exclude content based on attributes. Explore our learning path for a quick introduction to these key elements.

Plus, as a thank you for reading this far, here’s our AsciiDoc Cheat Sheet with 33 of the most important AsciiDoc Syntax Elements. For more templates and guides, check out our download section.

AsciiDoc cheat sheet with 33 essential syntax elements

Best Practices for Writing in AsciiDoc

Over the years, the AsciiDoc community has established several conventions that make your documents easier to write, review, and maintain:

One Sentence Per Line. Place each sentence on its own line. AsciiDoc treats consecutive lines as a single paragraph, so the output looks the same. The advantage: version control systems like Git can track changes at the sentence level, making diffs far more readable. Learn more about how Git changed technical writing.

This is the first sentence.
This is the second sentence.
They render as a single paragraph.

Use Includes for Large Documents. Break your content into separate files and combine them with include:: — see our include directive guide for details. This keeps each file manageable and allows multiple authors to work on different sections simultaneously:

= User Manual
include::chapters/introduction.adoc[]
include::chapters/installation.adoc[]
include::chapters/configuration.adoc[]

Use Attributes for Repeated Values. Define product names, version numbers, or URLs as attributes. When they change, you update them in one place:

:product-name: adoc Studio
:version: 4.0

Download {product-name} {version} today.

Organize Images in a Dedicated Folder. Set the :imagesdir: attribute to keep your image paths clean:

:imagesdir: images

image::screenshot.png[My Screenshot]

Use Conditional Directives for Multi-Target Publishing. If your document targets different audiences or formats, use ifdef, ifndef, or ifeval to control what gets included:

ifdef::backend-pdf[]
This text only appears in the PDF output.
endif::[]

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. Check out our ISO-ready stylesheets or the Tufte style for inspiration.

It’s important to distinguish between AsciiDoc converters. For example, Asciidoctor uses different “languages” for PDF and HTML. While HTML relies on CSS, AsciidoctorPDF requires a separate tool for PDF conversion. In contrast, tools like adoc&nbsp;Studio use CSS for both HTML and PDF, allowing you to maintain a single stylesheet for all exports.

We use AsciiDoc to ensure our project documents are styled consistently across different formats, from client presentations to internal reports. It allows us to maintain uniformity while also being flexible with how we display certain information, especially in terms of accessibility across multiple formats like HTML, PDF, or ePub.
Daniel Roberts, LavaRoofing CEO

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?

Comparison of markup languages versus WYSIWYG editors

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.

AsciiDoc vs. Markdown

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:

To make the differences more tangible, here’s a side-by-side comparison of key features:

Feature AsciiDoc Markdown
Tables Built-in, with column spanning and alignment Basic only (via GFM extension)
Footnotes Native support Extension required
Table of Contents Auto-generated via :toc: attribute Not supported
Admonitions (NOTE, TIP, WARNING) Built-in Not supported
File Includes include::file.adoc[] Not supported
Cross-References <<anchor-id>> with auto-numbering Not supported
Conditional Content ifdef / ifndef directives Not supported
Document Attributes (Variables) :name: value with {name} Not supported
Custom Styling CSS for HTML and PDF Limited
Syntax Highlighting Built-in with source blocks Extension required
Standardization Eclipse Foundation Working Group No universal standard (many flavors)
Output Formats HTML, PDF, EPUB, DocBook, man pages Primarily HTML

As you can see, AsciiDoc covers many features natively that Markdown either doesn’t support at all or requires third-party extensions for. This is especially relevant for teams that need a reliable, consistent syntax across projects.

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.
Peter Kenny, AsciiDoc User

Migrating from Markdown to AsciiDoc

Many writers start with Markdown and later discover they need AsciiDoc’s more advanced features. For a comprehensive step-by-step approach, read our full migration playbook. You can also learn how Ping Identity migrated to AsciiDoc. The good news: migrating is straightforward and there are tools that make it easier.

Automated Conversion Tools. You don’t have to convert files manually. Several tools can help:

  • Kramdoc (also known as markdown2asciidoc): Converts Markdown files to AsciiDoc format while preserving structure and formatting.
  • Pandoc: A universal document converter that supports Markdown-to-AsciiDoc conversion among dozens of other formats. Run pandoc -f markdown -t asciidoc input.md -o output.adoc.

Common Pitfalls When Migrating:

  • Markdown’s **bold** becomes *bold* in AsciiDoc (single asterisks). Double asterisks have a different meaning in AsciiDoc (unconstrained bold).
  • Links are reversed: Markdown uses [text](url) while AsciiDoc uses url[text].
  • Image syntax differs: Markdown’s ![alt](path) becomes image::path[alt] in AsciiDoc. Note the double colon for block images.

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

adoc Studio app icon

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. Explore all features.

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 built adoc Coach, a syntax completion menu that suggests and explains syntax directly at your cursor.

Asciidoctor

Asciidoctor logo

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. See our detailed comparison of Asciidoctor vs adoc Studio.

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 and IntelliJ IDEA, 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 the 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

For a complete walkthrough, see our export guide for every OS.

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.

Terminal showing complex Asciidoctor export scripts for multi-format output

Resources and Further Reading

This should be enough for a broad overview of 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.

FAQs (Frequently Asked Questions)

What is AsciiDoc?
AsciiDoc is a lightweight, human-readable markup language designed for writing technical documents, books, blogs, and more. It allows you to write in plain text and convert your content into multiple formats such as HTML, PDF, and DocBook.

Who created AsciiDoc and when?
AsciiDoc was created by Stuart Rackham in 2002. He developed it to offer a simple yet powerful alternative to traditional document formatting tools.

How does AsciiDoc compare to Markdown and other markup languages?
While Markdown is popular for its simplicity, AsciiDoc provides a more standardized syntax, extensive built-in features, and greater flexibility for handling complex documents. This makes it ideal for detailed technical documentation and large-scale projects.

What are the advantages of using AsciiDoc over WYSIWYG editors like MS Word or Google Docs?
AsciiDoc separates content from presentation, making version control and collaboration easier. It supports single-source publishing across multiple formats and integrates seamlessly with tools like Git, which is especially valuable in Docs-as-Code workflows.

How can I get started with AsciiDoc?
You can begin by writing a simple text file using AsciiDoc syntax. Tools such as Asciidoctor, adoc Studio, or extensions for IDEs like Visual Studio Code allow you to preview and convert your documents into various output formats.

Which output formats does AsciiDoc support?
AsciiDoc can be converted into a variety of formats including HTML, PDF, DocBook, and ePub. The available formats may depend on the tools you use for conversion.

Can I style my AsciiDoc documents with CSS?
Yes. When generating HTML output, you can link custom CSS files to style your document. Some tools even allow you to apply a single stylesheet for both HTML and PDF outputs.

What tools and editors are recommended for working with AsciiDoc?
Popular options include:
  • adoc Studio: A dedicated, native AsciiDoc editor that provides an intuitive interface and live preview.
  • Asciidoctor: A command-line toolchain for processing AsciiDoc files.

  • IDEs like Visual Studio Code and IntelliJ IDEA also support AsciiDoc through plugins and extensions.


How does AsciiDoc integrate with version control systems?
Since AsciiDoc files are plain text, they work well with version control systems such as Git. This enables smooth collaboration and a Docs-as-Code approach.

What is the difference between AsciiDoc and Asciidoctor?
AsciiDoc is the markup language — the syntax and rules for writing documents. Asciidoctor is a software tool (processor) that reads AsciiDoc files and converts them into output formats like HTML or PDF. Think of it like this: AsciiDoc is the language, Asciidoctor is the compiler.

How do I create a table of contents in AsciiDoc?
Simply add the :toc: attribute to your document header. AsciiDoc will automatically generate a clickable table of contents based on your section headings. You can control placement with :toc: left, :toc: right, or :toc: preamble.

Can I include mathematical formulas in AsciiDoc?
Yes. AsciiDoc supports STEM (Science, Technology, Engineering, Mathematics) notation. Add :stem: latexmath to your document header, then use stem:[formula] for inline math or a dedicated stem block for display equations. This supports LaTeX math syntax. See our STEM formulas tutorial.

How do I structure a large document with multiple files?
Use the include:: directive to split your document into separate files. Create a main file that includes chapter files like include::chapter-01.adoc[]. Each chapter can be edited independently. This is especially useful for books, manuals, and collaborative projects. Learn more about composite documents.

Can I migrate my existing Markdown files to AsciiDoc?
Yes. Tools like Kramdoc and Pandoc can automatically convert Markdown to AsciiDoc. For example, run pandoc -f markdown -t asciidoc input.md -o output.adoc on the command line. After conversion, review the output to ensure all formatting was preserved correctly. Read our full migration playbook for more details.