Commit fb2a25d8 authored by Sarah White's avatar Sarah White Committed by Dan Allen
Browse files

migrate documentation for the AsciiDoc language

parents
name: asciidoc
title: AsciiDoc
version: current
asciidoc:
attributes:
source-language: asciidoc@
xrefstyle: short@
listing-caption: Example@
nav:
- modules/ROOT/nav.adoc
- modules/document/nav.adoc
- modules/attributes/nav.adoc
- modules/toc/nav.adoc
- modules/sections/nav.adoc
- modules/text/nav.adoc
- modules/blocks/nav.adoc
- modules/macros/nav.adoc
- modules/lists/nav.adoc
- modules/tables/nav.adoc
- modules/verbatim/nav.adoc
- modules/stem/nav.adoc
- modules/directives/nav.adoc
- modules/subs/nav.adoc
- modules/pass/nav.adoc
- modules/ROOT/nav-compare.adoc
- modules/attributes/nav-ref.adoc
* xref:asciidoc-vs-markdown.adoc[]
* Key Concepts
//* xref:get-started.adoc[]
** xref:doctypes.adoc[]
** xref:elements.adoc[]
** xref:attributes:get-started.adoc[]
= AsciiDoc Versus Markdown
:description: A brief comparison of AsciiDoc and Markdown.
The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.
In other words, the goal is to be able to _write without friction_.
== Getting your start with Markdown
The defacto lightweight markup language is Markdown.
(At least, Markdown is what you call it at first).
The main advantage of Markdown lies in its primitive syntax: its manual and cheatsheet are one and the same.
But this advantage is also its greatest weakness.
As soon as authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves resorting to embedded HTML or seeking out more feature-rich implementations.
Markdown has become a maze of different implementations, termed "`flavors`", which make a universal definition evasive.
NOTE: The IETF has declared "`there is no such thing as "invalid" Markdown.`"
See https://tools.ietf.org/html/rfc7763#section-1.1[This Is Markdown! Or: Markup and Its Discontents^].
Here's how the story inevitably goes.
You start out with Markdown.
Then it's Markdown + X.
Then Markdown + X + Y.
And down the rabbit hole you go.
What's worse, X and Y often require you to sprinkle in HTML, unnecessarily coupling content with presentation and wrecking portability.
Your instinct to choose Markdown is good.
There are just better options.
== Graduating to AsciiDoc
AsciiDoc presents a more sound alternative.
The AsciiDoc syntax is more concise than (or at least as concise as) Markdown.
At the same time, AsciiDoc offers power and flexibility without requiring the use of HTML or "`flavors`" for essential syntax such as tables, description lists, admonitions (tips, notes, warnings, etc.) and table of contents.
It's important to understand that AsciiDoc was initially designed as a plain-text alternative to the DocBook XML schema.
AsciiDoc isn't stuck in a game of whack-a-mole trying to satisfy publishing needs like Markdown.
Rather, the AsciiDoc syntax was explicitly designed with the needs of publishing in mind, both print and web.
If the need arises, you can make full use of the huge choice of tools available for a DocBook workflow using Asciidoctor's DocBook converter.
That's why mapping to an enterprise documentation format like DocBook remains a key use case for AsciiDoc.
And yet, AsciiDoc is simple enough to stand in as a better flavor of Markdown.
But what truly makes AsciiDoc the right investment is that its syntax was designed to be extended as a core feature.
This extensibility not only means that AsciiDoc has a lot more to offer, with room to grow, it also fulfills the objective of ensuring your content is maximally reusable.
// This section originated from the discussion in {url-org}/asciidoctor.org/issues/34[issue #34].
== Comparison by example
The following table shows the AsciiDoc syntax as it compares to Markdown.
Since AsciiDoc supports a broader range of syntax than Markdown, this side-by-side comparison focuses mainly on areas where the syntax overlaps.
.A selection of AsciiDoc language features compared to Markdown
[#asciidoc-vs-markdown%autowidth]
|===
|Language Feature |Markdown |AsciiDoc
|Bold (constrained)
a|
[source,markdown]
----
**bold**
----
a|
[source]
----
*bold*
----
|Bold (unconstrained)
a|
[source,markdown]
----
**b**old
----
a|
[source]
----
**b**old
----
|Italic (constrained)
a|
[source,markdown]
----
*italic*
----
a|
[source]
----
_italic_
----
|Italic (unconstrained)
|_n/a_
a|
[source]
----
__i__talic
----
|Monospace (constrained)
a|
[source,markdown]
----
`monospace`
----
a|
[source]
----
`monospace`
----
|Monospace (unconstrained)
a|
[source,markdown]
----
`m`onospace
----
a|
[source]
----
``m``onospace
----
|Link with label
a|
[source,markdown]
----
[Asciidoctor](https://asciidoctor.org)
----
a|
[source]
----
https://asciidoctor.org[Asciidoctor]
----
|Relative link
a|
[source,markdown]
----
[user guide](user-guide.html)
----
a|
[source]
----
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]
----
|File link
a|
[source,markdown]
----
[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)
----
a|
[source]
----
link:{site-url}/assets/mydoc.pdf[get the PDF]
----
|Cross reference
a|
[source,markdown]
----
See [Usage](#_usage).
<h2 id="_usage">Usage</h2>
----
a|
[source]
----
See <<_usage>>.
== Usage
----
|Block ID (aka anchor)
a|
[source,markdown]
----
<h2 id="usage">Usage</h2>
----
a|
[source]
----
[#usage]
== Usage
----
|Inline anchor
|_n/a_
a|
[source]
----
. [[step-1]]Download the software
----
|Inline image w/ alt text
a|
[source,markdown]
----
![Logo](/images/logo.png)
----
a|
[source]
----
image:logo.png[Logo]
----
|Block image w/ alt text
|_n/a_
a|
[source]
----
image::logo.png[Logo]
----
|Section heading*
a|
[source,markdown]
----
## Heading 2
----
a|
[source]
----
== Heading 2
----
|Blockquote*
a|
[source,markdown]
----
> Quoted text.
>
> Another paragraph in quote.
----
a|
[source]
----
____
Quoted text.
Another paragraph in quote.
____
----
|Literal block
a|
[source,markdown]
----
$ gem install asciidoctor
----
a|
.Indented (by 1 or more spaces)
[source]
----
$ gem install asciidoctor
----
.Delimited
[source]
----
....
$ gem install asciidoctor
....
----
|Code block*
a|
[source,markdown]
----
```java
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
```
----
a|
[source]
....
[source,java]
----
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
----
....
|Unordered list
a|
[source,markdown]
----
* apples
* orange
* temple
* navel
* bananas
----
a|
[source]
----
* apples
* oranges
** temple
** navel
* bananas
----
|Ordered list
a|
[source,markdown]
----
1. first
2. second
3. third
----
a|
[source]
----
. first
. second
. third
----
|Thematic break (aka horizontal rule)*
a|
[source,markdown]
----
***
* * *
---
- - -
___
_ _ _
----
a|
[source]
----
'''
----
|Typographic quotes (aka "`smart quotes`")
|Enabled through an extension switch, but offer little control in how they are applied.
a|
[source]
----
The `'90s popularized a new form of music known as "`grunge`" rock.
It'll turn out to have an impact that extended well beyond music.
----
|Document header
a|
.Slapped on as "`front matter`"
[source,markdown]
----
---
layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
---
----
a|
.Native support!
[source]
----
= Writing posts
:awestruct-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages
----
|Admonitions
|_n/a_
a|
[source]
----
TIP: You can add line numbers to source listings by adding the word `numbered` in the attribute list after the language name.
----
|Sidebars
|_n/a_
a|
[source]
----
.Lightweight Markup
****
Writing languages that let you type less and express more.
****
----
|Block titles
|_n/a_
a|
[source]
----
.Grocery list
* Milk
* Eggs
* Bread
----
|Includes
|_n/a_
a|
[source]
----
\include::intro.adoc[]
----
|URI reference
a|
[source,markdown]
----
Go to the [home page][home].
[home]: https://example.org
----
a|
[source]
----
:home: https://example.org
Go to the {home}[home page].
----
|Custom CSS classes
|_n/a_
a|
[source]
----
[.path]_Gemfile_
----
|===
+*+ Asciidoctor also supports the Markdown syntax for this language feature.
You can see that AsciiDoc has the following advantages over Markdown:
* AsciiDoc uses the same number of markup characters or less when compared to Markdown in nearly all cases.
* AsciiDoc uses a consistent formatting scheme (i.e., it has consistent patterns).
* AsciiDoc can handle all permutations of nested inline (and block) formatting, whereas Markdown often falls down.
* AsciiDoc handles cases that Markdown doesn't, such as a proper approach to inner-word markup, source code blocks and block-level images.
NOTE: Certain Markdown flavors, such as Markdown Extra, support additional features such as tables and description lists.
However, since these features don't appear in "`plain`" Markdown, they're not included in the comparison table.
But they're supported natively by AsciiDoc.
Asciidoctor, which is used for converting AsciiDoc on GitHub and GitLab, emulates "`the good parts`" of the Markdown syntax, like headings, blockquotes and fenced code blocks, making migration from Markdown to AsciiDoc fairly simple.
For details about migration, see #url-home/docs/asciidoc-syntax-quick-reference/#markdown-compatibility[Markdown Compatibility#.
////
===== Description Lists in AsciiDoc
[source]
----
a term:: a description
another term:: another description
----
They can even hold code examples:
[source]
....
term with code example:: a description
+
[source,java]
----
public class Person {
}
----
....
===== Tables in AsciiDoc
An AsciiDoc table can be written as a series of lists which use a vertical bar as the list marker:
[source]
----
[cols=3]
|===
|a
|b
|c
|1
|2
|3
|===
----
Which appears as:
[cols=3]
|===
|a
|b
|c
|1
|2
|3
|===
Markdown Extra supports tables and description lists, too; but it's not Markdown.
Also, unlike Markdown Extra, AsciiDoc can apply formatting to cells.
////
= Comment Lines and Blocks
[#comment-lines]
== Comment lines
.Line comment syntax
----
// A single-line comment.
----
Single-line comments can be used to divide elements, such as two adjacent lists.
== Comment blocks
.Block comment syntax
----
////
A block comment.
Notice it's a delimited block.
////
----
= Document Types
Article (`article`)::
The default doctype.
In DocBook, includes the appendix, abstract, bibliography, glossary, and index sections.
Book (`book`)::
Builds on the article doctype with the additional ability to use a top-level title as part titles, includes the appendix, dedication, preface, bibliography, glossary, index, and colophon.
There's also the concept of a multi-part book, but the distinction from a regular book is determined by the content.
A book only has chapters and special sections, whereas a multi-part book is divided by parts that each contain one or more chapters or special sections.
Man page (`manpage`)::
Used for producing a roff or HTML-formatted manual page (man page) for Unix and Unix-like operating systems.
This doctype instructs the parser to recognize a special document header and section naming conventions for organizing the AsciiDoc content as a man page.
See xref:asciidoctor:backends:manpage/convert-to-man-page.adoc[] for details on how structure a man page using AsciiDoc and generate it with Asciidoctor.
Inline (`inline`)::
Asciidoctor only.
There may be cases when you only want to apply inline AsciiDoc formatting to input text without wrapping it in a block element.
For example, in the Asciidoclet project (AsciiDoc in Javadoc), only the inline formatting is needed for the text in Javadoc tags.
// {asciidoclet-ref}[Asciidoclet project]
== Inline doctype
The rules for the inline doctype are as follows:
* Only a single paragraph is read from the AsciiDoc source.
* Inline formatting is applied.
* The output is not wrapped in the normal paragraph tags.
Given the following input:
[source]
https://asciidoctor.org[AsciiDoc] is a _lightweight_ markup language...
Processing it with the options `doctype=inline` and `backend=html5` produces:
[source,html]
<a href="https://asciidoctor.org">AsciiDoc</a> is a <em>lightweight</em> markup language&#8230;
The inline doctype allows the Asciidoctor processor to cover the full range of applications, from unstructured (inline) text to full, standalone documents!
= AsciiDoc Elements
There are two kinds of elements in AsciiDoc, block elements and inline elements.
[#block-element]
== Block elements
A [.term]*block element* is one or more contiguous lines of content in an AsciiDoc document.
Block elements are typically referred to simply as [.term]*blocks*.
Examples of blocks include tables, lists, paragraphs, section titles, delimited blocks, and block macros like the block image macro (`image::[]`).