migrate documentation for the AsciiDoc language

docs/asciidoc/antora.yml

+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

docs/asciidoc/modules/ROOT/nav-compare.adoc

+* xref:asciidoc-vs-markdown.adoc[]

docs/asciidoc/modules/ROOT/nav.adoc

+* Key Concepts
+//* xref:get-started.adoc[]
+** xref:doctypes.adoc[]
+** xref:elements.adoc[]
+** xref:attributes:get-started.adoc[]

docs/asciidoc/modules/ROOT/pages/asciidoc-vs-markdown.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.
+////

docs/asciidoc/modules/ROOT/pages/comment.adoc

+= 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.
+////
+----

docs/asciidoc/modules/ROOT/pages/doctypes.adoc

+= 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!

docs/asciidoc/modules/ROOT/pages/elements.adoc

+= 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::[]`).
+These types of blocks are easy to identify because they're separated from other blocks by a blank line.
+However, not all blocks may be separated by a blank line from an adjacent block.
+For instance, block titles and block attribute lists are individual block elements that are placed on adjacent, contiguous lines.
+An attribute entry is also a block, that when defined in a document header is often directly adjacent to other blocks.
+
+Blocks can be nested within other blocks.
+An attribute entry in a header is also an example of a block nested within another block.
+That's because the attribute entry is a block and the entire document header is a block.
+
+[#inline-element]
+== Inline elements
+
+An [.term]*inline element* performs an operation on a subset of content within a <<block-element,block element>>.
+Inline elements include inline macros such as the icon macro (`icon:[]`) and xref macro (`<< >>`, `xref:[]`), attribute references, and text marked up by inline formatting (italic, bold, etc.).

docs/asciidoc/modules/ROOT/pages/index.adoc

+= AsciiDoc Language Documentation
+
+[caption="Migration in Progress"]
+TIP: This documentation is in migration.
+If you're looking for the current Asciidoctor and AsciiDoc documentation, visit https://asciidoctor.org/docs.

docs/asciidoc/modules/ROOT/partials/glossary.adoc

+admonition:: a callout paragraph or block that has a label or icon indicating its priority.
+
+backend:: a moniker for the expected output format; used as a key to select which converter to use; often used interchangeably with the name of a converter (i.e., the "html5" backend").
+
+block attribute:: an attribute associated with a delimited block or paragraph; these attributes can affect processing of the block, and are available to block processors, but cannot be referenced using an attribute reference.
+
+built-in attribute:: a document attribute that controls processing, integrations, styling, and localization.
+
+cross reference:: a link from one location in the document to another location marked by an anchor.
+
+document attribute:: an attribute associated with the document (node); in other words, an attribute in the global document attributes dictionary; the value of these attributes can be referenced using an attribute reference; if defined in the header, the document attribute is known as a header attribute.
+
+environment attribute:: a dynamic document attribute that pertains to, or gives information about, the runtime environment.
+
+header attribute:: a document attribute defined in the document header; visible from all nodes in the document; often required for global settings such as the source highlighter or icons mode.
+
+list continuation:: a plus sign (`+`) on a line by itself that connects adjacent lines of text to a list item.
+
+macro attribute:: an attribute associated with a block or inline macro; these attributes can affect processing of the macro, and are available to macro processors, but cannot be referenced using an attribute reference.
+
+predefined attribute:: a document attribute defined for convenience; often used for inserting special content characters.
+
+quoted text:: text which is enclosed in special punctuation to give it emphasis or special meaning.
+
+user-defined attribute:: a document attribute defined by the content author; used for storing reusable content, and controlling conditional inclusion.

docs/asciidoc/modules/ROOT/partials/to-latest-syntax.adoc

+= Migrate from Asciidoctor 0.1.4 to Asciidoctor 1.5.0
+//Dan Allen
+//v1.1, 2014-08-10
+//:page-layout!:
+:description: A guide that assists with migration from Asciidoctor 0.1.4 to 1.5.0.
+:keywords: Asciidoctor 1.5, migrate to Asciidoctor 1.5, Asciidoctor 1.5 migration, migrating to Asciidoctor 1.5, migrating to Asciidoctor, compat mode, Asciidoctor compat mode, compat-mode
+
+We decided to rework some of the AsciiDoc syntax in Asciidoctor 1.5.0 in an effort to make it more consistent, deterministic and easy to learn.
+You can learn more about the changes in the link:/release-notes/asciidoctor-1-5-0[Asciidoctor 1.5.0 release notes].
+
+Compatibility is very important to us, so we've added a compatibility mode as well as a transitional syntax to ease migration from Asciidoctor 0.1.4 to Asciidoctor 1.5.0.
+This document explains how to enable <<Compat mode,compat(ibility) mode>>, if you're not yet ready to migrate, as well as the <<Migration scenarios,migration scenarios>>, for when you are ready to make the switch.
+It also draws your attention to a few minor changes you'll need to be aware of that could affect your content.
+
+== Compat mode
+
+If you can't migrate right now, you can activate compatibility mode by setting the document-level `compat-mode` attribute or by using a setext-style (i.e., two-line) document title.
+
+In compat mode, most of Asciidoctor 1.5.0's _syntax modifications_ that deviate from the legacy AsciiDoc syntax are reverted.
+This mode does not disable syntax unique to Asciidoctor, such as inline icons (e.g., pass:[icon:fire[\]]).
+
+You can define the `compat-mode` attribute in the document header:
+
+ :compat-mode:
+
+using the `-a` commandline flag:
+
+ -a compat-mode
+
+or using the `attributes` option in the API:
+
+ attributes: %w(compat-mode)
+
+Alternatively, you can enable compat mode by using a setext-style (i.e., two-line) section title:
+
+----
+Document Title
+==============
+
+Content parsed in compat-mode by default.
+----
+
+Since setext-style headings are typically used in older AsciiDoc documents, this convention allows Asciidoctor to accommodate these older documents without having to wake any sleeping giants ;)
+
+You can set `compat-mode` anywhere in the flow of a document.
+
+.Setting and unsetting compat-mode in a document
+-----
+:compat-mode: // <1>
+
+Sometimes you feel 'compat'.
+
+:compat-mode!: // <2>
+
+Sometimes you _don't_.
+-----
+<1> Set compat-mode within the body of a document.
+<2> Unset compat-mode using a bang (`!`) within the body of a document.
+
+Compat mode will be supported for the foreseeable future to avoid unnecessary disruption to your content.
+
+If you want to begin migration to the modern syntax, read on.
+
+== Migration scenarios
+
+There are several scenarios that are affected by Asciidoctor 1.5.0's changes to the AsciiDoc syntax:
+
+* Monospaced normal text (text that doesn't contain any AsciiDoc syntax)
+* Monospaced text without substitutions (you want to prevent the monospaced text from being interpreted)
+* Monospaced text with substitutions (you want the monospaced text to be interpreted)
+* Smart quote shorthand
+
+Let's first consider the legacy syntax used in each of these examples.
+
+=== Legacy syntax
+
+Here's the legacy syntax (Asciidoctor 0.1.4 and earlier) for the scenarios listed above.
+
+* pass:[+monospaced normal text+ or `monospaced normal text`]
+* pass:[`{asciidoctor-version} holds the version`] (attribute is not replaced)
+* pass:[+The Asciidoctor version is {asciidoctor-version}+] (attribute is replaced)
+* pass:[``double quoted'' and `single quoted'] (quotes are curved)
+
+=== New syntax
+
+Here are those same three scenarios using the syntax in Asciidoctor 1.5.0.
+
+* pass:[`monospaced normal text`]
+* pass:[`+{asciidoctor-version} holds the version+`] (attribute is not replaced)
+* pass:[`The Asciidoctor version is {asciidoctor-version}`] (attribute is replaced)
+* pass:["`double quoted`" and '`single quoted`'] (quotes are curved)
+
+WARNING: To escape single smart quotes in the legacy syntax, you place a single backslash in front of the start quote (e.g., pass:[\``single quoted'']).
+In the new syntax, you need to use a backslash before the start quote and before the end quote (e.g., pass:[\'`single quoted\`']).
+That's because pass:[`'] is an unconstrained (anywhere) right smart quote replacement.
+
+Before jumping to the new syntax, you need to understand that it won't be parsed correctly by Asciidoctor 0.1.4.
+Unfortunately, we can't control when Asciidoctor is upgraded on services like GitHub, so there will be a period of time when you will need to use a syntax that works on both versions.
+So what do we do?
+The answer, use the transitional syntax.
+
+=== Transitional syntax
+
+The transitional syntax allows you to pin-point the locations in your document that you'll eventually want to migrate to the modern syntax, but can't yet until Asciidoctor 0.1.4 is phased out.
+
+To use the transitional syntax, simply add the role `x-` in front of the legacy syntax to indicate that you want Asciidoctor 1.5.0 to use the old behavior.
+Naturally, Asciidoctor 0.1.4 already understands the old syntax and will simply ignore the role.
+
+.Transitional syntax
+* pass:[`monospaced normal text`] (*No transitional syntax necessary!*)
+* pass:[[x-\]`{asciidoctor-version} holds the version`] (attribute is not replaced)
+* pass:[[x-\]+The Asciidoctor version is {asciidoctor-version}+] (attribute is replaced)
+* “double quotes” and ‘single quotes’
+
+[NOTE]
+====
+There isn't transitional syntax for curved (i.e., smart) quotes.
+Instead, we encourage you to enter the smart quotes directly into your document.
+It is UTF-8 after all!
+
+Refer to https://smartquotesforsmartpeople.com[Smart Quotes for Smart People], https://www.kryogenix.org/days/2013/10/17/smart-quotes-for-smart-ubuntu-people[Smart Quotes for Smart Ubuntu (Linux) People] or https://fsymbols.com/keyboard/linux/compose/[Linux Keyboard Shortcuts for Text Symbols] for instructions on how to type these characters.
+====
+
+Let's consider an example.
+
+.Using the transitional syntax
+[caption="Example: "]
+====
+Assume you want to put italics inside of monospaced text.
+If you want the syntax to work in both Asciidoctor and AsciiDoc Python, you need to do one of the following:
+
+[loweralpha]
+. Enable the `compat-mode` attribute on the document and enter the text as:
+
+ +cat _filename_+
+
+. Don't enable the `compat-mode` attribute and enter the text as:
+
+ [x-]+cat _filename_+
+
+You can think of `[x-]` as a local compat mode setting.
+====
+
+If you aren't worried about how the document renders on services like GitHub, you can start using the modern syntax immediately.
+
+== Migration cheatsheet
+
+The following table provides a migration cheatsheet that compares the legacy, transitional and modern syntax side-by-side.
+
+.Syntax migration cheatsheet
+[cols="1m,1m,1m,1"]
+|===
+|Legacy |Transitional |Modern |Rendered
+
+|pass:['italic text']
+d|N/A
+|pass:[_single quoted_]
+|_italic text_
+
+|pass:[+monospaced text+]
+d|N/A
+|pass:[`monospaced text`]
+|`monospaced text`
+
+|pass:[`monospaced text`]
+d|N/A
+|pass:[`monospaced text`]
+|`monospaced text`
+
+|pass:[`{asciidoctor-version}`]
+|pass:[[x-\]`{asciidoctor-version}`]
+|pass:[`+{asciidoctor-version}+`]
+|[x-]`{asciidoctor-version}`
+
+|pass:[+{asciidoctor-version}+]
+|pass:[[x-\]+{asciidoctor-version}+]
+|pass:[`{asciidoctor-version}`]
+|[x-]+{asciidoctor-version}+
+
+|pass:[``double quoted'']
+|pass:[“double quoted”]
+|pass:["`double quoted`"]
+|“double quoted”
+
+|pass:[`single quoted']
+|pass:[‘single quoted’]
+|pass:['`single quoted`']
+|‘single quoted’
+|===
+
+== TOC (Table of Contents) positioning
+
+Say goodbye to the `toc2` attribute.
+It's deprecated!
+
+As of Asciidoctor 1.5.0, the `toc2`, `toc-placement` and `toc-position` attributes have been combined into a more expressive `toc` attribute.
+The `toc` attribute does it all!
+It's now responsible for enabling the table of contents and specifying the location where it should appear.
+
+For example, to activate the table of contents in the left sidebar, define the `toc` attribute _in the document header_ with the value of `left`.
+
+.Enable the (left) sidebar table of contents
+----
+= Document Title
+Author Name
+:toc: left
+----
+
+If you want to position the table of contents manually, then you'd set the value of the `toc` attribute to `macro` (_not_ `manual`) and use the `toc::[]` macro to indicate the location where the table of contents should appear.
+
+.Position the sidebar explicitly
+----
+= Document Title
+Author Name
+:toc: macro
+
+some content
+
+toc::[]
+
+more content
+----
+
+The following list shows the permitted values for the `toc` attribute:
+
+* auto (default value when the `toc` attribute value is blank)
+* left
+* right
+* preamble
+* macro
+
+We recommend you remove all other attributes that affect the positioning of the toc from your document or launch scripts (i.e., `toc2`, `toc-placement` and `toc-position`).
+
+For more information about the table of contents, see the #user-toc,Table of Contents# section of the user manual.
+
+== Font Awesome upgrade (3.2.1 -> 4.1)
+
+The Asciidoctor 1.5.0 release brought an upgrade from Font Awesome 3.2.1 to 4.1.
+Font Awesome 4 introduced a new naming pattern for icons.
+This won't affect any of the built-in use of Font Awesome, such as admonition icons, but it does affect the inline icon macro.
+If you use the inline icon macro, consult the https://github.com/FortAwesome/Font-Awesome/wiki/Upgrading-from-3.2.1-to-4#new-icon-names[mapping between old and new names] to ensure you don't have any broken images.
+
+If you want to continue to use the old icon names, you can incorporate the https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/compat/font-awesome-3-compat.css[font-awesome-3-compat.css] file from the Asciidoctor repository into your generated HTML using a #docinfo-file,docinfo file#.

docs/asciidoc/modules/attributes/examples/counter.adoc

+// tag::base[]
+[caption=""]
+.Parts{counter2:index:0}
+|===
+|Part Id |Description
+
+|PX-{counter:index}
+|Description of PX-{index}
+
+|PX-{counter:index}
+|Description of PX-{index}
+|===
+// end::base[]

docs/asciidoc/modules/attributes/examples/id.adoc

+// tag::block-id-brackets[]
+[[notice]]
+This paragraph gets a lot of attention.
+// end::block-id-brackets[]
+
+// tag::block-id-shorthand[]
+[#notice]
+This paragraph gets a lot of attention.
+// end::block-id-shorthand[]
+
+// tag::anchor[]
+// tag::anchor-brackets[]
+[[bookmark-a]]Inline anchors make arbitrary content referenceable.
+// end::anchor-brackets[]
+
+// tag::anchor-shorthand[]
+[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#
+// end::anchor-shorthand[]
+
+anchor:bookmark-c[]Use a cross reference to link to this location.
+
+[[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.
+// end::anchor[]
+
+// tag::anchor-wrong[]
+[[anchor-point]]* list item text
+// end::anchor-wrong[]
+
+// tag::anchor-list[]
+* First item
+* [[step2]]Second item
+* Third item
+// end::anchor-list[]
+
+// tag::anchor-header[]
+=== Version 4.9 [[version-4_9]]
+// end::anchor-header[]
+
+// tag::anchor-header-extra[]
+=== [[current]]Version 4.9 [[version-4_9]]
+// end::anchor-header-extra[]
+
+// tag::anchor-xreflabel[]
+[[tiger-image,Image of a tiger]]
+.This image represents a Bengal tiger also called the Indian tiger
+image::tiger.png[]
+// end::anchor-xreflabel[]
+
+// tag::anchor-macro[]
+anchor:tiger-image[Image of a tiger]
+// end::anchor-macro[]

docs/asciidoc/modules/attributes/nav-ref.adoc

+* Reference Tables
+** xref:ref-environment.adoc[]
+** xref:ref-document.adoc[]
+** xref:ref-character-replacement.adoc[]

docs/asciidoc/modules/attributes/nav.adoc

+.Document Attributes
+* xref:document-attributes.adoc[]
+* xref:attribute-entries.adoc[]
+** xref:names-and-values.adoc[]
+** xref:wrap-values.adoc[]
+** xref:attribute-entry-substitutions.adoc[]
+** xref:inline-attribute-entries.adoc[]
+* Built-in Document Attributes
+** xref:built-in-attributes.adoc[]
+** xref:reference-built-in-attributes.adoc[]
+** xref:boolean-attributes.adoc[]
+** xref:unset-built-in-attributes.adoc[]
+* Custom Document Attributes
+** xref:custom-attributes.adoc[]
+** xref:reference-custom-attributes.adoc[]
+** xref:unresolved-references.adoc[]
+// ** Unset Custom Attributes
+* xref:assignment-precedence.adoc[]
+//** Using Document Attributes from the CLI
+//** Using Document Attributes from the API
+
+.Element Attributes
+* xref:element-attributes.adoc[]
+** xref:positional-and-named-attributes.adoc[]
+* xref:styles.adoc[]
+* xref:ids.adoc[]
+* xref:options.adoc[]
+* xref:roles.adoc[]

docs/asciidoc/modules/attributes/pages/assignment-precedence.adoc

+= Manage Document Attribute Assignment Precedence
+:navtitle: Attribute Assignment Precedence
+
+== Default attribute value precedence
+
+The attribute assignment precedence, listed from highest to lowest, is:
+
+. An attribute defined using the API or CLI
+. An attribute defined in the document
+. The default value of the attribute, if applicable
+
+Let's use the `imagesdir` attribute to show how precedence works.
+
+The default value for the `imagesdir` attribute is an empty string.
+Therefore, if the `imagesdir` attribute is not assigned a value (either in the document, API, or CLI), the processor will assign it the default value of empty string.
+If the `imagesdir` attribute is set in the document (meaning assigned a new value, such as `images`), that value will override the default value.
+Finally, if a value is assigned to the `imagesdir` attribute via the API or CLI, that value will override both the default value and the value assigned in the document.
+
+It's possible to alter this order of precedence using a modifier, covered in the next section.
+
+== Altering the assignment precedence
+
+You can allow the document to reassign an attribute that is defined via the API or CLI by adding the `@` precedence modifier to the end of the attribute value or the end of the attribute name.
+Adding this modifier lowers the precedence so that an assignment in the document still wins out.
+We sometimes refer to this as "`soft setting`" the attribute.
+This feature can be useful for assigning default values for attribute, but still letting the document control its own fate.
+
+NOTE: The `@` modifier is removed before the assignment is made.
+
+Here's an example that shows how to set the `imagesdir` from the CLI with a lower precedence:
+
+ $ asciidoctor -a imagesdir=images@ doc.adoc
+
+Alternately, you can place the modifier at the end of the attribute name:
+
+ $ asciidoctor -a imagesdir@=images doc.adoc
+
+It's now possible to override the value of the `imagesdir` attribute from within the document:
+
+[source]
+----
+= Document Title
+:imagesdir: new/path/to/images
+----
+
+To soft unset an attribute from the CLI or API, you can use the following syntax:
+
+ !name=@
+
+The leading `!` unsets the attribute while the `@` lowers the precedence of the assignment.
+This assignment is almost always used to unset a default value while still allowing the document to assign a new one.
+One such example is `sectids`, which is enabled by default.
+`!sectids=@` switches the setting off.
+
+Let's update the attribute assignment precedence list defined earlier to reflect this additional rule:
+
+. An attribute passed to the API or CLI whose value does not end in `@`
+. An attribute defined in the document
+. An attribute passed to the API or CLI whose value or name ends in `@`
+. The default value of the attribute, if applicable
+
+Regardless of whether the precedence modifier is applied, an attribute assignment always overrides the default value.

docs/asciidoc/modules/attributes/pages/attribute-entries.adoc

+= Attribute Entries
+
+== What is an attribute entry?
+
+Before you can use a document attribute in your document, you have to declare it.
+An [.term]*attribute entry* is the primary mechanism for defining a document attribute in an AsciiDoc document.
+You can think of an attribute entry as a global variable assignment for AsciiDoc.
+The document attribute it creates becomes available from that point forward in the document.
+Attribute entries are also frequently used to toggle features.
+
+An attribute entry consists of two parts: an attribute *name* and an attribute *value*.
+The attribute name comes first, followed by the optional value.
+Each attribute entry must be entered on its own line.
+An attribute entry starts with an opening colon (`:`), directly followed by the attribute's name, and then a closing colon (`:`).
+This [.term]*sets* -- that is, turns on -- the document attribute so you can use it in your document.
+
+[source]
+----
+:name-of-an-attribute: <.>
+----
+<.> The attribute's name is directly preceded with a opening colon (`:`) and directly followed by a closing colon (`:`).
+
+In many cases, you explicitly assign a value to a document attribute by entering information after its name in the attribute entry.
+The value must be offset from the closing colon (`:`) by at least one space.
+Be aware that xref:attribute-entry-substitutions.adoc[header substitutions] automatically get applied to the value by default.
+
+[source]
+----
+:name-of-an-attribute: value of the attribute <.>
+----
+<.> An explicitly assigned value is offset from the closing colon (`:`) by at least one blank space.
+At the end of the value, press kbd:[Enter].
+
+Some built-in attributes don't require a value to be explicitly assigned in an attribute entry because they're a boolean attribute or have a default value.
+
+[source]
+----
+:name-of-an-attribute: <.>
+----
+<.> If you don't want to explicitly assign a value to the attribute, press kbd:[Enter] after the closing colon (`:`).
+
+The values of built-in boolean attributes are always blank because their only accepted value is an _empty string_.
+Other built-in attributes may have a default value.
+If you set a built-in attribute and leave its value blank, Asciidoctor assigns the default value, if it has one, to the attribute at processing time.
+
+== Where can I use an attribute entry?
+
+An attribute entry is typically defined in the document header.
+When set it the document header, the attribute is available to the entire document until it is reset or unset.
+The attribute's value can be reassigned or the attribute unset at any subsequent point in the document, unless the attribute is locked (typically by defining it using the CLI or API).
+
+Many, but not all, document attributes can be set, assigned a value, or unset in the document's body (anywhere below the document header).
+When you set an attribute in the body, it's visible from the point it's set until it's unset.
+See the xref:ref-document.adoc[] for where in a document each attribute can be set.
+
+Finally, document attributes can also be set, assigned values, and unset via the CLI and API, but these methods don't use the attribute entry syntax.
+When an attribute is set from the command line or API, it's defined for the whole document and can't be changed in the document header or body unless `@` is added to the end of the value.
+See xref:assignment-precedence.adoc[] for more information.
+The one exception to this rule is the `sectnums` attribute, which can always be changed.
+
+////
+An exclamation point (`!`) before (or after) the attribute name unsets the attribute.
+
+[source]
+----
+:!name: <1>
+----
+<1> The leading `!` indicates this attribute should be unset.
+In this case, the value is ignored.
+
+An attribute entry must start at the beginning of the line.
+If the attribute entry follows a paragraph, it must be offset by a blank line.
+////

docs/asciidoc/modules/attributes/pages/attribute-entry-substitutions.adoc

+= Customize Attribute Entry Substitutions
+
+The AsciiDoc processor automatically applies substitutions from the header substitution group to the value of an attribute entry prior to the assignment, regardless of where the attribute entry is declared in the document.
+The header substitution group, which replaces xref:subs:special-characters.adoc[special characters] and xref:subs:attributes.adoc[attribute references] in text, is applied to the values of attribute entries, regardless of whether the entries are defined in the header or in the document body.
+This is the same group that gets applied to metadata lines (author and revision information) in the document header.
+
+That means that any inline formatting in an attribute value isn't interpreted because:
+
+. inline formatting is not applied when Asciidoctor sets an attribute, and
+. inline formatting is not applied when an attribute is referenced since the relevant substitutions come before attributes are resolved.
+
+[#pass-macro]
+== Change substitutions when assigning a value
+
+If you want the value of an attribute entry to be used *as is* (not subject to substitutions), or you want to alter the substitutions that are applied, you can enclose the value in the xref:pass:pass-macro.adoc[inline pass macro] (i.e., `\pass:[]`).
+The inline pass macro accepts a list of zero or more substitutions in the target slot, which can be used to control which substitutions are applied to the value.
+If no substitutions are specified, no substitutions will be applied.
+
+In order for the inline macro to work in this context, it must completely surround the attribute value.
+If it's used anywhere else in the value, it will be ignored.
+
+Here's how to prevent substitutions from being applied to the value of an attribute entry:
+
+[source]
+----
+:cols: pass:[.>2,.>4]
+----
+
+This might be useful if you're referencing the attribute in a place that depends on the unaltered text, such as the value of the `cols` attribute on a table.
+
+Here's how we can apply the xref:subs:quotes.adoc[quotes substitution] to the value of an attribute entry:
+
+[source]
+----
+:app-name: pass:quotes[MyApp^2^]
+----
+
+Internally, the value is stored as `MyApp<sup>2</sup>`.
+You can inspect the value stored in an attribute using this trick:
+
+[source]
+----
+[subs=attributes+]
+------
+{app-name}
+------
+----
+
+You can also specify the substitution using the single-character alias, `q`.
+
+[source]
+----
+:app-name: pass:q[MyApp^2^]
+----
+
+The inline pass macro kind of works like an attribute value preprocessor.
+If the processor detects that an inline pass macro completely surrounds the attribute value, it:
+
+. reads the list of substitutions from the target slot of the macro
+. unwraps the value from the macro
+. applies the substitutions to the value
+
+If the macro is absent, the value is processed with the header substitution group.
+
+== Change substitutions when referencing an attribute
+
+You can also change the substitutions that are applied to an attribute at the time it is resolved.
+This is done by manipulating the substitutions applied to the text where it is referenced.
+For example, here's how we could get the processor to apply quote substitutions to the value of an attribute:
+
+[source]
+----
+:app-name: MyApp^2^
+
+[subs="specialchars,attributes,quotes,replacements,macros,post_replacements"]
+The application is called {app-name}.
+----
+
+Notice that we've swapped the order of the `attributes` and `quotes` substitutions.
+This strategy is akin to post-processing the attribute value.

docs/asciidoc/modules/attributes/pages/boolean-attributes.adoc

+= Set and Unset a Boolean Attribute
+// [#boolean-attribute]
+
+A boolean attribute is a built-in attribute that acts like a toggle.
+Its sole function is to turn on a feature or behavior.
+
+== Constructing an attribute entry for a boolean attribute
+
+A boolean attribute is set with an attribute entry in the header or body of a document.
+Its value is always left blank because boolean attributes only accept an _empty string_ value, which Asciidoctor automatically assigns at processing time.
+
+[source]
+----
+:name-of-a-boolean-attribute: <.>
+----
+<.> On a new line, type a colon (`:`), directly followed by the attribute's name and then another colon (`:`).
+After the closing colon, press kbd:[Enter].
+The attribute is now set and its behavior will be applied to the document.
+
+== Setting a boolean attribute
+
+Let's use an attribute entry to turn on the built-in boolean attribute named `sectanchors`.
+When `sectanchors` is set, it xref:sections:title-links.adoc#anchor[activates an anchor in front of a section title] when a cursor hovers over it.
+
+[source]
+----
+= Document Title
+:sectanchors: <.>
+----
+<.> The value of `sectanchors` is always left empty because it's a boolean attribute.
+
+== Unsetting a boolean attribute
+
+Boolean document attributes can be unset by adding a bang symbol (`!`) directly in front of or after the attribute's name in an attribute entry.
+The attribute entry must be on its own line.
+
+[source]
+----
+:!name-of-a-boolean-attribute:
+----
+
+Let's use an attribute entry to turn off the built-in boolean attribute named `sectids`.
+Asciidoctor automatically sets `sectids` at processing time unless you unset it.
+The `sectids` attribute xref:sections:ids.adoc[generates an ID for each section] from the section's title.
+
+[source]
+----
+= Document Title
+:!sectids: <.>
+----
+<.> On a new line, type a colon (`:`), directly followed by a bang symbol (`!`), the attribute's name, and then another colon (`:`).
+After the closing colon, press kbd:[Enter].
+The attribute is now unset and its behavior won't be applied to the document.
+
+Once an attribute is unset, its behavior is deactivated.
+When `sectids` is unset, Asciidoctor will not generate IDs from section titles at processing time.

docs/asciidoc/modules/attributes/pages/built-in-attributes.adoc

+= Set and Define Built-In Document Attributes
+// [#set-built-in]
+
+Asciidoctor has numerous attributes reserved for special purposes.
+*Built-in attributes* add, configure, and control common features in a document.
+Many built-in attributes only take effect when defined in the document header with an attribute entry.
+
+== Use an attribute's default value
+
+Many built-in attributes have a default value.
+When you want to activate a built-in attribute and assign it its default value, you can leave the value in the attribute entry empty.
+
+For example, to turn on the xref:toc:index.adoc[Table of Contents for a document], you set the `toc` attribute using an attribute entry in the document header.
+
+[source]
+----
+= Title of Document
+:toc:
+----
+
+The default value of an activated attribute will be assigned at processing time, if:
+
+. it has a default value, and
+. the value in the attribute entry is left empty
+
+In the example above, the default value of `auto` will be assigned to `toc` since the value was left empty in the attribute entry.
+
+== Override an attribute's default value
+
+You may not want to use the default value of a built-in attribute.
+In the next example, we'll override the default value of an attribute that Asciidoctor sets automatically.
+The built-in attribute `doctype` is automatically set and assigned a value of `article` at processing time.
+However, if you want to use AsciiDoc's book features, the `doctype` attribute needs to be assigned the `book` value.
+
+[source]
+----
+= Title of My Document
+:doctype: book <.>
+----
+<.> Set `doctype` in the document header and assign it the value `book`.
+Explicit values must be offset from the closing colon (`:`) by at least one space.
+
+To override an attribute's default value, you have to explicitly assign a value when you set the attribute.
+The value assigned to an attribute in the document header replaces the default value (assuming the attribute is not locked via the CLI or API).
+
+//Change to override a default value with a user-defined value
+=== Override a default asset directory value with a user-defined value
+
+You can also use the built-in asset directory attributes to customize the base path to images (default: `_empty_`), icons (default: `./images/icons`), stylesheets (default: `./stylesheets`) and JavaScript files (default: `./javascripts`).
+
+.Replace the default values of the built-in asset directory attributes
+[source]
+----
+= My Document
+:imagesdir: ./images
+:iconsdir: ./icons
+:stylesdir: ./styles
+:scriptsdir: ./js
+----
+
+The four built-in attributes in the example above have default values that are automatically set at processing time.
+However, in the example, they're being set and assigned explicit values in the document header.
+This explicit user-defined value replaces the default value (assuming the attribute is not locked via the CLI or API).
+
+////
+Many built-in attributes have a built-in value that is designated as the default value.
+This default value is assigned when the attribute is set and its value is left empty.
+For example, the xref:sections:id.adoc#separator[ID word separator attribute] can accept <<user-values,user-defined values>> and it has one default value.
+If you set `idseparator` and leave the value empty, the default value will be assigned automatically when the document is processed.
+
+[source]
+----
+:idseparator: // <1>
+----
+<1> The words in automatically generated IDs will be separated with an underscore (`_`), the attribute's default value, because the value is empty.
+
+To override the default value of an attribute, you have to explicitly assign a new value when you set the attribute.
+
+[source]
+----
+:idseparator: - // <1>
+----
+<1> The words in automatically generated IDs will be separated with a hyphen (`-`).
+The value must be offset from the attribute's name by a space.
+////

docs/asciidoc/modules/attributes/pages/counter.adoc

+= Counters
+// document attributes and counters are NOT the same thing, but modifying a document attribute with the same name as the counter modifies the counter at the same time.
+
+Counters are used to store and display ad-hoc sequences of numbers or latin characters.
+They are designed for simple use cases.
+Possible uses include inline itemized lists, paragraph numbers and serial item numbers.
+
+A counter is implemented as a specialized document attribute.
+You declare and display a counter using an augmented attribute reference, in which the attribute name is prefixed with `counter:` (e.g., `+{counter:name}+`).
+Since counters are attributes, counter names follow the same rules as xref:names-and-values.adoc#user-defined[attribute names].
+The most important rule to note is that letters in counter names _must be lowercase_.
+
+The counter value is incremented and displayed every time the `counter:` attribute reference is used.
+The term [.term]*increment* means advance to the next value in the sequence.
+If the counter value is an integer, add 1.
+If the counter value is a character, move to the next letter in the Latin alphabet.
+The default start value of a counter is 1.
+
+To create a sequence starting at 1, use the simple form `+{counter:name}+` as shown here:
+
+[source]
+The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
+
+Here's the resulting output:
+
+====
+:!seq1:
+The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
+====
+
+To increment the counter without displaying it (i.e., to skip an item in the sequence), use the `counter2` prefix instead:
+
+[source]
+{counter2:seq1}
+
+WARNING: A `counter2` attribute reference on a line by itself will produce an empty paragraph.
+You'll need to adjoin it to the nearest content to avoid this side effect.
+
+To display the current value of the counter without incrementing it, reference the counter name as you would any other attribute:
+
+[source]
+{counter2:pnum}This is paragraph {pnum}.
+
+To create a character sequence, or start a number sequence with a value other than 1, specify a start value by appending it to the first use of the counter:
+
+[source]
+Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries.
+
+CAUTION: Character sequences either run from a,b,c,...x,y,z,{,|... or A,B,C,...,X,Y,Z,[,... depending on the start value.
+Therefore, they aren't really useful for more than 26 items.
+
+The start value of a counter is only recognized if the counter is _unset_ at that point in the document.
+Otherwise, the start value is ignored.
+
+To reset a counter attribute, unset the corresponding attribute using an attribute entry.
+The attribute entry must be adjacent to a block or else it is ignored.
+
+[source]
+----
+The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
+
+:!seq1:
+Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries.
+----
+
+This gives:
+
+====
+:!seq1:
+The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
+
+:!seq1:
+Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries.
+====
+
+Here's a full example that shows how to use a counter for part numbers in a table.
+
+[source]
+----
+include::example$counter.adoc[tag=base]
+----
+
+Here's the output of that table:
+
+====
+include::example$counter.adoc[tag=base]
+====