AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.
AsciiDoc provides all the semantic elements you need to write and publish technical books. You’ll also find AsciiDoc to be an ideal fit for documentation. And yet, it’s simple enough to use for READMEs or taking notes. Explore the possibilities by browsing these screenshots.
When you write in AsciiDoc, you use plain text. That means the bulk of what you type are the words you want to communicate. You only add markup characters when you need to encode meaning that can’t otherwise be inferred. For example, a section title starts with a series of equals signs and an unordered list item begins with one or more asterisks. Try writing AsciiDoc in the editor below to see for yourself!
This is an interactive editor. Use it to try AsciiDoc.
A list item
Another list item
puts 'Hello, World!'AsciiDoc is designed to strike a balance between systematic, machine-oriented syntax and natural language. This design affords AsciiDoc the ability to capture and encode nearly all the semantics of a highly-structured language while still being readable in source form.
Want to see how AsciiDoc stacks up against alternatives? Browse the sample documents in this section to compare.
<?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> <info> <title>Book Title</title> <date>2022-01-15</date> <author> <personname> <firstname>Doc</firstname> <surname>Writer</surname> </personname> <email>doc@example.org</email> </author> <authorinitials>DW</authorinitials> <revhistory> <revision> <revnumber>2.0.1</revnumber> <date>2022-01-15</date> <authorinitials>DW</authorinitials> </revision> </revhistory> <cover role="front"> <mediaobject> <imageobject> <imagedata fileref="cover.png" contentwidth="1050" contentdepth="1600"/> </imageobject> </mediaobject> </cover> </info> <preface> <title>Preface</title> <simpara>The story behind the story.</simpara> </preface> <chapter xml:id="_chapter_title"> <title>Chapter Title</title> <simpara> A paragraph with <emphasis role="strong">bold</emphasis> and <emphasis>italic</emphasis> text. </simpara> <figure> <title>Image title</title> <mediaobject> <imageobject> <imagedata fileref="an-image.jpg" align="center"/> </imageobject> <textobject><phrase>An image</phrase></textobject> </mediaobject> </figure> <simpara> The <literal><link></literal> tag is used for source-to-source links, like <xref xl:href="a-book.xml">a book</xref>, and external links, like <xref xl:href="https://eclipse.org">Eclipse</xref>. </simpara> <note> <simpara>One of five built-in admonition block types.</simpara> </note> </chapter> <chapter xml:id="_another_chapter_title"> <title>Another Chapter Title</title> <literallayout class="monospaced">A preformatted paragraph is represented by the <literallayout> tag.</literallayout> <simpara> The following program listing contains a Ruby function named <literal>hello</literal> that prints <quote role="double">Hello, World!</quote>. </simpara> <programlisting language="ruby" linenumbering="numbered">def hello name = 'World' puts "Hello, #{name}!" end</programlisting> <simpara>That’s all she wrote!</simpara> </chapter> </book>
DocBook is an XML schema for writing books and manuals about technical subjects. It has an extensive catalog of tags for denoting content structures and elements. Although well-supported by tools, writing in DocBook is tedious because the content is overshadowed by the markup, there are a lot of tags to remember, and XML indentation can be a major distraction.
= Book Title Doc Writer <doc@example.org> v2.0.1, 2022-01-15 :doctype: book :front-cover-image: cover.png[,1050,1600] [preface] == Preface The story behind the story. include::chapter-1.adoc[leveloffset=1] include::chapter-2.adoc[leveloffset=1]
= Chapter Title A paragraph with *bold* and _italic_ text. .Image title image::an-image.jpg[align=center] The `xref` macro is used for source-to-source links, like xref:a-book.adoc[]. An external link to https://eclipse.org[Eclipse]. NOTE: One of five built-in admonition block types.
= Another Chapter Title Text indented by one space is preformatted. The following source code block contains a Ruby function named `hello` that prints "`Hello, World!`". [%linenums,ruby] ---- def hello name = 'World' puts "Hello, #{name}!" end ---- That's all she wrote!
Content is the central focus in AsciiDoc. The document starts off with no ceremonial prologue, much of the structure is inferred from its line-oriented arrangement, there’s no indentation needed, and content is marked up with shorthand notations instead of XML tags. And yet, you can still produce DocBook from AsciiDoc to tie into existing toolchains.
# Heading 1 A paragraph with **bold** and *italic* text. A link to [Eclipse](https://eclipse.org). A reusable link to [GitLab](gitlab).  ## Heading 2 * Unordered list item * Nest items by aligning marker with text of parent item * Another unordered list item **NOTE:** An admonition can be emulated using a bold label. ### Heading 3 Text indented by four spaces is preformatted. A code block with a Ruby function named `hello` that prints “Hello, World!”: ```ruby def hello name = 'World' puts "Hello, #{name}!" end ``` [gitlab]: https://gitlab.com
Markdown is a lightweight markup language for producing HTML. Markdown builds on basic plain text conventions for formatting content. While approachable to a broad audience, it stops short of being a technical writing language. The need for syntax extensions quickly enters the picture. In reality, Markdown is the basis for a variety of markup languages that often deviate widely.
= Document Title :toc: :url-gitlab: https://gitlab.eclipse.org A paragraph with *bold* and _italic_ text. A link to https://eclipse.org[Eclipse]. A reusable link to {url-gitlab}[GitLab]. image::an-image.png[An image,800] == Section title * Unordered list item ** Add another marker to make a nested item * Another unordered list item NOTE: One of five built-in admonition block types. === Subsection title Text indented by one space is preformatted. A source block with a Ruby function named `hello` that prints "`Hello, World!`": [,ruby] ---- def hello name = 'World' puts "Hello, #{name}!" end ----
AsciiDoc appears strikingly similar to Markdown, making way for an easy transition. Where AsciiDoc shines is in its depth. AsciiDoc provides all the essential elements in technical writing out of the box. No variants needed. Its syntax can be elaborated without having to fundamentally change the language, assuring users that it’s still standard AsciiDoc.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> <topic id="required_id"> <title>Topic Title</title> <shortdesc>A brief description of topic.</shortdesc> <body> <section id="section_title"> <title>Section title</title> <p>A paragraph with <b>bold</b> and <i>italic</i> text.</p> <fig> <title>Image title</title> <image href="an-image.jpg" align="center" alt="An image"/> </fig> <p>The <codeph><xref></codeph> tag is used for source-to-source links, like <xref href="a-topic.dita"/>, and external links. An external link, <xref href="https://eclipse.org" format="html" scope="external">Eclipse</xref>, has to specify the format and scope.</p> <pre frame="all">A preformatted paragraph is represented by the <pre> tag.</pre> <p>The following source code block contains a Ruby function named <codeph>hello</codeph> that prints <q>Hello, World!</q>.</p> <codeblock outputclass="language-ruby">def hello name = 'World' puts "Hello, #{name}!" end</codeblock> </section> <section id="sibling_section_title"> <title>Sibling section title</title> <p>DITA doesn't have nested sections.</p> </section> </body> </topic>
DITA is an XML schema for representing a broad range of information. Its architecture encourages content modularity and reuse, portable references, and controlled extension of its vocabulary. These goals are met using a complex system of XML tags, concepts, and toolchains. DITA’s complexity means it has a substantial learning curve and is sparsely supported.
= Topic Title :description: A brief description of topic. == Section title A paragraph with *bold* and _italic_ text. .Image title image::an-image.jpg[align=center] The `xref` macro is used for source-to-source links, like xref:a-topic.adoc[]. An external link to https://eclipse.org[Eclipse]. Text indented by one space is preformatted. The following source code block contains a Ruby function named `hello` that prints "`Hello, World!`". [,ruby] ---- def hello name = 'World' puts "Hello, #{name}!" end ---- === Subsection title AsciiDoc supports nested sections.
AsciiDoc fits the same architectural goals into an XML-free package and is widely supported. Documents can be partitioned into units of content and reused with the include directive. Document references are defined source-to-source and translated into links between published files. Syntax extensions invite new markup and integrations while keeping the language consistent.
************** Document Title ************** Section title ============= A paragraph with **bold** and *italic* text. An external link to `Eclipse <https://eclipse.org>`_. A reusable link to `GitLab`_. .. image:: /images/an-image.png :height: 600 :width: 800 :alt: An image Subsection title ---------------- * Unordered list item * Nest items by aligning marker with text of parent item * Another unordered list item .. note:: One of two supported admonition block types. Sub-subsection title ^^^^^^^^^^^^^^^^^^^^ :: Preformatted text must be indented by two spaces and follow a text block that ends with the :: marker. The following source code block contains a Ruby function named ``hello`` that prints "Hello, World!". .. code-block:: ruby def hello name = 'World' puts "Hello, #{name}!" end .. _GitLab: https://gitlab.eclipse.org
reStructuredText is plain text markup for use in docstrings and formal documentation. It offers an extensible syntax for producing structured output. It’s line-oriented design keeps the content clear and the separation of blocks evident. However, its reliance on indentation, non-traditional notation, and syntax variations make the language esoteric and hard for newcomers to grasp.
= Document Title :imagesdir: images :url-gitlab: https://gitlab.eclipse.org == Section title A paragraph with *bold* and _italic_ text. An external link to https://eclipse.org[Eclipse]. A reusable link to {url-gitlab}[GitLab]. image::an-image.png[An image,800] === Subsection title * Unordered list item ** Add another marker to make a nested item * Another unordered list item NOTE: One of five built-in admonition block types. ==== Sub-subsection title Text indented by one space is preformatted. The following source code block contains a Ruby function named `hello` that prints "`Hello, World!`". [,ruby] ---- def hello name = 'World' puts "Hello, #{name}!" end ----
AsciiDoc aims to provide an easy-to-read, what-you-see-is-what-you-get syntax. It attains this goal by making most indentation insignificant, using clear block boundaries, and relying on conventional notation. AsciiDoc is composed of a few patterns, such as delimited blocks, macros, and formatting pairs. A newcomer can pick up the syntax mostly by intuition alone.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Docs | Document Title</title> <meta name="keywords" content="comparison, sample"> <link rel="stylesheet" href="css/doc.css"> </head> <body> <header class="navbar"> <div class="logo"><img src="logo.svg" alt="ACME"></div> <nav class="main"> <ul> <li><a href="products.html">Products</a></li> <li><a href="resources.html">Resources</a></li> <li><a href="company.html">Company</a></li> </ul> </nav> </header> <main> <article class="doc"> <header> <h1>Document Title</h1> <p class="by-line"> <span class="author">Doc Writer</span> </p> </header> <section class="body"> <p> A paragraph with <strong>bold</strong> and <em>italic</em> text. A link to <a href="https://eclipse.org">Eclipse</a>. </p> <figure> <img src="an-image.jpg" alt="An image" width="800"> </figure> <section id="section-title"> <h2>Section title</h2> <ul> <li><span>Unordered list item</span></li> <ul> <li><span>Use a nested <code><ul></code> tag to create a nested item</span></li> </ul> <li><span>Second unordered list item</span></li> </ul> <div class="admonition note"> <span class="label">NOTE</span> <div class="content"> <p> An admonition can be emulated using a bold label and some CSS. </p> </div> </div> <section id="subsection-title"> <h3>Subsection title</h3> <pre>Text inside a <pre> tag is preformatted.</pre> <p> A code block with a Python function named <code>hello</code> that prints <q>Hello, World</q>: </p> <pre class="source"><code data-lang="ruby">def hello name = 'World' puts "Hello, #{name}!" end</code></pre> </section> </section> </section> </article> </main> <footer> <div class="company-info">...</div> <div class="links">...</div> </footer> </body> </html>
As the most basic building block of the web, HTML gives structure to web content. But it also assumes a lot of presentation responsibilities. It’s rare to find an HTML document focused solely on content. Its forte is in assembling high fidelity web pages, not as a technical writing format. It has all the ceremony of XML with only a fraction of its presentation-agnostic semantics.
= Document Title Doc Writer :keywords: comparison, sample :url-gitlab: https://gitlab.eclipse.org A paragraph with *bold* and _italic_ text. A link to https://eclipse.org[Eclipse]. A reusable link to {url-gitlab}[GitLab]. image::an-image.jpg[An image,800] == Section title * Unordered list item ** Add another marker to make a nested item * Another unordered list item NOTE: One of five built-in admonition block types. === Subsection title Text indented by one space is preformatted. A source block with a Ruby function named `hello` that prints "`Hello, World!`": [,ruby] ---- def hello name = 'World' puts "Hello, #{name}!" end ----
Although AsciiDoc was initially conceived as a DocBook shorthand, it’s now mostly used to generate HTML. By producing the HTML, content is not impacted by redesigns and content variations, like slides or eBooks, can be created from the same source. AsciiDoc processors bundle a stylesheet that requires no web development to achieve a professional look.
The AsciiDoc Language specification was launched to ensure that AsciiDoc continues to evolve and that it’s processed consistently by implementations across language runtimes, authoring environments, and application integrations. The specification is managed and governed by the AsciiDoc Language project and, at a higher level, by the AsciiDoc Working Group at the Eclipse Foundation. Development of the specification is currently underway.
Write, validate, and preview your AsciiDoc content in your favorite text editor, IDE, or browser.
Convert AsciiDoc documents to HTML, DocBook, PDF, and more using an AsciiDoc processor.
Publish content using site generators or build tools that understand how to process AsciiDoc.