asciidoctor / asciidoc-docs

The source files in this repository served as the initial contribution for the AsciiDoc Language specification project at Eclipse. This repository is now archived.

Asciidoctor

Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in AsciiDoc. You can find the documentation for these projects at https://docs.asciidoctor.org.

In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment using Asciidoctor.js.

This document is also available in the following languages:
简体中文 | Deutsch | Français | 日本語

Key documentation

• Asciidoctor Documentation

• AsciiDoc Language Documentation

• AsciiDoc Syntax Quick Reference

Sponsors

We want to recognize our sponsors for their commitment to improving the state of technical documentation by supporting this project. Thank you sponsors! Without your generous support, Asciidoctor would not be possible.

You can support this project by becoming a sponsor through OpenCollective.

AsciiDoc Processing and Built-in Converters

AsciiDoc is the language.
Asciidoctor is the processor.

Asciidoctor reads the AsciiDoc source, as shown in the panel on the left in the image below, and converts it to publishable formats, such as HTML 5, as shown rendered in the panel on the right.

Asciidoctor provides built-in converters for three output formats by default: HTML 5, DocBook 5, and man page (short for manual page). Additional converters, such as PDF and EPUB 3, are provided by separate gems. Asciidoctor also provides an out-of-the-box HTML experience complete with a default stylesheet and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).

Asciidoctor Ecosystem

Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it. Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js.

Installing an Asciidoctor processor is just the beginning of your publishing experience. Asciidoctor gives you access to a ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments:

• Asciidoctor Diagram

• Maven plugin and site module

• Gradle plugin

• Asciidoclet

• reveal.js converter

• EPUB 3 converter

• IntelliJ plugin

• web browser extensions

• and more

Asciidoctor is the successor to AsciiDoc.py. If you’re using AsciiDoc.py, see Migrate from AsciiDoc.py to learn how to upgrade to Asciidoctor.

Requirements

Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of Ruby:

• CRuby (aka MRI) 2.7 - 3.3

• JRuby 9.2 - 9.4

• TruffleRuby (GraalVM)

🔥

If you’re using a non-English Windows environment, you may bump into an Encoding::UndefinedConversionError when invoking Asciidoctor. To solve this issue, we recommend overriding the default external and internal character encodings to utf-8. You can do so by setting the RUBYOPT environment variable as follows: RUBYOPT="-E utf-8:utf-8" Once you make this change, all your Unicode headaches should be behind you. If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. Asciidoctor is optimized to work with UTF-8 as the default encoding.

Installation

Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) named asciidoctor. The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle). Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).

Linux package managers

The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release.

• Alpine Linux (asciidoctor)

• Arch Linux (asciidoctor)

• Debian (asciidoctor)

• Fedora (asciidoctor)

• OpenSUSE (rubygem-asciidoctor)

• Ubuntu (asciidoctor)

If you want to use a version of Asciidoctor that’s newer than what is installed by the package manager, see the gem installation instructions.

apk (Alpine Linux)

To install the gem on Alpine Linux, open a terminal and type:

$ sudo apk add asciidoctor

pacman (Arch Linux)

To install the gem on Arch-based distributions, open a terminal and type:

$ sudo pacman -S asciidoctor

APT

On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. To install the package, open a terminal and type:

$ sudo apt-get install -y asciidoctor

DNF

On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. To install the package, open a terminal and type:

$ sudo dnf install -y asciidoctor

macOS

Homebrew

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions first.

Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type:

$ brew install asciidoctor

Homebrew installs the asciidoctor gem into an exclusive prefix that’s independent of system gems.

MacPorts

You can also use MacPorts, another package manager for macOS, to install Asciidoctor. If you don’t have MacPorts on your computer, complete the installation instructions first.

Once MacPorts is installed, you’re ready to install the asciidoctor gem via the Asciidoctor port. Open a terminal and type:

$ sudo port install asciidoctor

Windows

To use Asciidoctor with Windows, you have two options.

Chocolatey

When you already use chocolatey on your machine, you can use:

choco install ruby

Then follow gem installation instructions.

Rubyinstaller

Or you use the Rubyinstaller, download the package for your Windows Version and after the installation go ahead with gem installation instructions.

gem install

Before installing Asciidoctor using gem install, you should set up RVM (or similar) to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem, or any other gem for that matter. When using RVM, gems are installed in a location isolated from the system. (You should never use the gem command to install system-wide gems).

Once you’ve installed Ruby using RVM, and you have activated it using rvm use 3.0, open a terminal and type:

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

Docker

See Installing Asciidoctor using Docker.

Bundler

1. Create a Gemfile in the root folder of your project (or the current directory)

2. Add the asciidoctor gem to your Gemfile as follows:

   source 'https://rubygems.org'
   gem 'asciidoctor'
   # or specify the version explicitly
   # gem 'asciidoctor', '2.0.22'

3. Save the Gemfile

4. Open a terminal and install the gem using:

   $ bundle

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.

Upgrade

If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don’t need to update the gem manually.

apk (Alpine Linux)

To upgrade the gem, use:

$ sudo apk add -u asciidoctor

APT

To upgrade the gem, use:

$ sudo apt-get upgrade -y asciidoctor

DNF

To upgrade the gem, use:

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

To upgrade the gem, use:

$ brew update
$ brew upgrade asciidoctor

MacPorts (macOS)

To upgrade the gem, use:

$ sudo port selfupdate
$ sudo port upgrade asciidoctor

gem install

If you previously installed Asciidoctor using the gem command, you’ll need to manually upgrade Asciidoctor when a new version is released. You can upgrade the gem by typing:

$ gem install asciidoctor

When you install a new version of the gem using gem install, you end up with multiple versions installed. Use the following command to remove the old versions:

$ gem cleanup asciidoctor

Usage

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it’s available, run the following in your terminal:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.22 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

Command line interface (CLI)

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html.

$ asciidoctor README.adoc

You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:

$ asciidoctor --help

For instance, to write the file to a different directory, use:

$ asciidoctor -D output README.adoc

The asciidoctor man page provides a complete reference of the command line interface.

Refer to the following resources to learn more about how to use the asciidoctor command.

• Process AsciiDoc using the CLI

• CLI options

Ruby API

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

To use Asciidoctor in your application, you first need to require the gem:

require 'asciidoctor'

You can then convert an AsciiDoc source file to an HTML file using:

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe

⚠️	When using Asciidoctor via the API, the default safe mode is :secure. In secure mode, several core features are disabled, including the include directive. If you want to enable these features, you’ll need to explicitly set the safe mode to :server (recommended) or :safe.

You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

If you want the full HTML document, enable the header_footer option as follows:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

If you need access to the parsed document, you can split the conversion into discrete steps:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

Keep in mind that if you don’t like the output Asciidoctor produces, you can change it! Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.

One easy way to customize the output piecemeal is by using the template converter. The template converter allows you to supply a Tilt-supported template file to handle converting any node in the document.

However you go about it, you can have 100% control over the output. For more information about how to use the API or to customize the output, see:

• Process AsciiDoc using the API

• API options

• Safe modes

Contributing

New contributors are always welcome! If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix.

Here are some ways you can contribute:

• by using prerelease (alpha, beta or preview) versions

• by reporting bugs

• by suggesting new features

• by writing or editing documentation

• by writing code with tests — No patch is too small.

  • fix typos

  • add comments

  • clean up inconsistent whitespace

  • write tests!

• by refactoring code

• by fixing issues

• by reviewing patches

The Contributing guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.

Getting Help

Asciidoctor is developed to help you easily write and publish your content. But we can’t do it without your input. If you need assistance or want to provide feedback, please follow the links to the resources listed on the Get Help page in the docs. Here’s a quick summary:

Project chat (Zulip)

https://chat.asciidoctor.org

Discussion list (archived)

https://discuss.asciidoctor.org

Social media (Twitter)

Follow @asciidoctor or search the #asciidoctor hashtag

Further information and documentation about Asciidoctor can be found on the project’s website.

Home | News | Docs

The Asciidoctor organization on GitHub hosts the project’s source code, issue tracker, and sub-projects.

Source repository (git)

https://github.com/asciidoctor/asciidoctor

Issue tracker

https://github.com/asciidoctor/asciidoctor/issues

Asciidoctor organization on GitHub

https://github.com/asciidoctor

Code of Conduct

The core Asciidoctor project is governed by the Code of Conduct for the Asciidoctor community of projects. By participating, you’re agreeing to honor this code. Let’s work together to make this a welcoming, professional, inclusive, and safe environment for everyone.

Versioning and Release Policy

This project adheres to semantic versioning (major.minor.patch). Typically, patch releases are only made for the current minor release. However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.

Copyright and License

Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. Use of this software is granted under the terms of the MIT License.

See the LICENSE for the full license text.

Authors

Asciidoctor is led by Dan Allen and Sarah White and has received contributions from many individuals in Asciidoctor’s awesome community. The project was initiated in 2012 by Ryan Waldron based on a prototype written by Nick Hengeveld for the Git website.

AsciiDoc.py was started and maintained by Stuart Rackham from 2002 to 2013 and has received contributions from many individuals in the AsciiDoc.py community.

Trademarks

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.

Changelog

Refer to the CHANGELOG for a complete list of changes in older releases.

asciidoc-docs's Issues

Change STEM intepreter to STEM notation

In the STEM section, the term "STEM interpreter" is being used to refer to the input variant, AsciiMath or LaTeX. For example:

You can use both interpreters in the same document. The value of the stem attribute merely sets the default interpreter.

However, an interpreter is the software that parses this input and displays the expression for viewing. The term we're looking for here is STEM notation since we're taking about how the input is classified (meaning whether it's assumed to be LaTeX or AsciiMath)

If STEM notation still doesn't seem like a good fit, here are two alternatives:

• STEM markup language
• STEM dialect

Move hard line breaks back to paragraph section

Hard line breaks should be covered in the "Paragraphs" section of the docs as they pertain specifically to paragraphs. The "Breaks" section should only cover breaks that are blocks, which are thematic breaks and page breaks.

Document [%autofit]

I think [%autofit] is not yet documented. I don't personally use this feature yet, but I saw another user mention it in this issue

Frame value topbot has been replaced by ends

The frame value "topbot" on tables has been replaced by "ends". "ends" is the complement to "sides". Update the documentation to use "ends" where "topbot" is currently used.

In the most recent version of Asciidoctor, the default stylesheet no longer supports "topbot", nor does the stylesheet used for this docs site.

Document the xref: syntax

For many years I've been using the following syntax when it comes to have chapter cross references:

:xrefstyle: short

<<my.adoc#myref>>

But sometimes I need to use both short and basic style. Thanks to Dan[1] I discovered the xref: syntax[2]:

:xrefstyle: short

xref:my.adoc#myref

xref:my.adoc#myref[xrefstyle=basic]

This syntax is not documented. Neither on the manual[3] nor the guide[4]. Maybe this should be documented in the "Customizing the Cross Reference Text" section[5] of the manual ? Something like:

You can also customize the label (short, basic or full) on each cross-reference using the xref: syntax. This syntax can be used for internal as well as external references:

Refer to xref:interalref[xrefstyle=basic]

Refer to xref:interalref[xrefstyle=full]

Refer to xref:external.adoc#externalref[xrefstyle=basic]

Refer to xref:external.adoc#externalref[xrefstyle=short]

WDYT?

[1] https://twitter.com/mojavelinux/status/1311398097226883072
[2] https://github.com/asciidoctor/asciidoctor/blob/master/features/xref.feature#L1049
[3] https://asciidoctor.org/docs/user-manual/
[4] https://asciidoctor.org/docs/asciidoc-writers-guide/
[5] https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text

Migrate AsciiDoc syntax quick reference

• Migrate the AsciiDoc syntax quick reference content to syntax-quick-reference.adoc in ROOT module
• Update examples as needed
• Turn included reference tables into xrefs to minimize content duplication
• Add [%collapsible.result] to example blocks that show rendered output

Complete documentation of how positional and named attributes are recognized.

While working on #33, which started out as a typo fix :-), I've realized that how positional attributes and named attributes are parsed is not explained, and certainly shouldn't be on modules/macros/pages/link-macro-attribute-parsing.adoc but rather on modules/attributes/pages/positional-and-named-attributes.adoc. I have strong doubts that I can explain the algorithm correctly or comprehensibly.

Missing info about shorthand values for inline pass macro

Hello!

I can't find the following information in new Asciidoc documentation:

The inline pass macro also accepts shorthand values for specifying substitutions.

• c = special characters
• q = quotes
• a = attributes
• r = replacements
• m = macros
• p = post replacements

https://web.archive.org/web/20201212034130/https://asciidoctor.org/docs/user-manual/#pass-macros

My suggestion is return back old variant of Asciidoc documentation, because new documentation is uncomplete.

Consolidate Header Set and Body Set columns in document attribute reference to Header Only

When we're talking about document attributes, all the writer needs to know is whether the document attribute must be set by the end of the header (i.e., Header Only). Otherwise, its implied that the attribute can be set anywhere, assuming it is not locked by the CLI or API. This change will also simplify the visual complexity of these tables.

The preface and appendix are best not to have a section title gap

Today, I want to use the Book Part feature, so I read Book Parts | Asciidoctor Docs.

= Multi-Part Book with Parts that Have Special Sections
Author Name <[email protected]>
:doctype: book

[preface]
= Book Preface

This is the preface for the whole book.

=== Preface Subsection

Chinchillas rule the world.

= Part 1

This is the introduction to the first part of our mud-encrusted journey.

== Chapter 1

There was mud...

[appendix]
= The Appendix

=== Basics

A multipart book can have appendixes, which should be defined at section level 0.

=== Subsections

Subsections of an appendix in a multipart book should start at level 2.

The preface and appendix have the = Part titles, then have some === subsection titles.

In my opinion, it is not great. It is inconvenient to manage documents. If do not have the gap, I can write the preface in a document, then include the preface include::preface.adoc[], It is OK. If have the gap, convert the preface.adoc, it throw a warn.

If do not have the gap as following:

[appendix]
= The Appendix

[appendix]
== Appendix 1

[appendix]
== Appendix 2

Then the converted document:

• Appendix A: The Appendix
• Appendix B: Appendix 1
• Appendix C: Appendix 2

Set up CHANGELOG file

Based on a preliminary structure like that for code:

= AsciiDoc Documentation Changelog

This document provides a high-level view of the changes introduced into the AsciiDoc Docs

== Released

New::

* Document feature something something (#xyzq)

Improvements::

* Add example about something  (#xyzq)

Fixes::

* Fix incorrect something (#xyzq)

Component / Build / Meta::

* Add alias for something 
* Move attribute to component descriptor

Questions:

Since we're not doing versions at the moment, do we want to group changes indicating when they went live, like by date, or do we just want to add inputs to the top of each appropriate list?

Is the purpose of this Changelog to keep a document version of each commit for comparison to the spec's initial contribution or for just general informational purposes?

Do we want this file stored in the root of the repository, or in a module?

Make distinction between default value and implied value if empty in document attributes reference

There is a difference between a default value (that which the processor assigns if the attribute is not set or unset) and an implied value when the value is empty.

One example of this is the toc attribute. The toc attribute is not set by default (no default value). If the toc attribute is set to an empty string, the processor implies that the value is auto. Another example is the icons attribute. Again, the attribute is not set by default. But if it is set to an empty value, the processor implies the value is image.

(Note however that the processor doesn't actually assign the implied value to the attribute. It just treats the empty value as the same as that value).

In the table, we can continue to use bold to represent the default value. However, for implicit values, they should be listed next to the value of empty. For example:

|toc
|_empty_ (auto), auto, left, right, preamble, macro

and

|icons
|_empty_ (image), image, font

I can't think of a case where an attribute has both a default value and an implicit value when blank. Thus far, these have been mutually exclusive (if only by chance).

Document the xref: syntax

For many years I've been using the following syntax when it comes to have chapter cross references:

:xrefstyle: short

<<my.adoc#myref>>

But sometimes I need to use both short and basic style. Thanks to Dan[1] I discovered the xref: syntax[2]:

:xrefstyle: short

xref:my.adoc#myref

xref:my.adoc#myref[xrefstyle=basic]

This syntax is not documented. Neither on the manual[3] nor the guide[4]. Maybe this should be documented in the "Customizing the Cross Reference Text" section[5] of the manual ? Something like:

You can also customize the label (short, basic or full) on each cross-reference using the xref: syntax. This syntax can be used for internal as well as external references:

Refer to xref:interalref[xrefstyle=basic]

Refer to xref:interalref[xrefstyle=full]

Refer to xref:external.adoc#externalref[xrefstyle=basic]

Refer to xref:external.adoc#externalref[xrefstyle=short]

WDYT?

[1] https://twitter.com/mojavelinux/status/1311398097226883072
[2] https://github.com/asciidoctor/asciidoctor/blob/master/features/xref.feature#L1049
[3] https://asciidoctor.org/docs/user-manual/
[4] https://asciidoctor.org/docs/asciidoc-writers-guide/
[5] https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text

Clarify when to enclose/not enclose an attribute in quotes in ifeval statement

On https://docs.asciidoctor.org/asciidoc/latest/directives/ifeval/, there are two examples of testing an attribute's value that could be clearer:

ifeval::["{backend}" == "html5"]
...
endif::[]

ifeval::[{sectnumlevels} == 3]
...
endif::[]

In the first example "{backend}" is in quotes. Why?
In the second example, {sectnumlevels} is not in quotes. Why?

It seems like in both examples you want to test the value of the attribute.

Setting multiple roles via attribute is not working

When trying to add multiple roles like in the exemple 4 from the documentation about roles: https://docs.asciidoctor.org/asciidoc/latest/attributes/role/

[role="role1,role2"]
****
This is a sidebar with two roles assigned to it, role1 and role2.
****

asciidoctor.js don't split the roles

Output:

<aside class="sidebar role1,role2"><p>This is a sidebar with two roles assigned to it, role1 and role2.</p></aside>

It works properly when using the shorhand syntaxe as in example 3 of the same doc page

It seems to be the case on all type of block I have tried.

For now i am able to patch it using a treeProcessor but it would be nice to know what is the intended syntax

registry.treeProcessor(function () {
    this.process((doc) => {
      doc.findBy({ }, image =>{
          const attributeRoles = (image.getAttribute('role') || '').split(',')
          image.setAttribute('role', attributeRoles.join(' '))
        })
    })
  })

.document-attributes-reference.adoc:.swp file breaking cloning

While cloning repository there is error:
error: invalid path 'docs/modules/attributes/pages/.document-attributes-reference.adoc:.swp'

It seems like leftover from editing :)

Wrongly formatted list continuation examples

In the section "lists continuation--attaching to an ancestor list", the AsciiDoc sources appear on only one line.

In case this is browser-dependant, here is how they are rendered on my screen (Firefox, Linux):

Add a dedicated page that covers the AsciiDoc table cell style

The AsciiDoc table cell style deserves it's own page. Unlike the other table cell styles, it actually changes how the content is parsed. And there are some things to know about it.

• The AsciiDoc table cell must be used if the content contains AsciiDoc block content (paragraph, listing block, etc); it is not needed if the cell only has inline formatting
• An AsciiDoc table cell is an embedded document
• An AsciiDoc table cell inherits attributes from the parent document (though there are some exceptions)
• Line comments are removed from the content before the table cell is parsed (unlike a normal AsciiDoc document)
• The content should begin on a new line (though this is just a recommendation atm)
• References are shared with the parent document
• Counters are shared with the parent document
• Footnotes are processed independently from the parent document

Fix grouping in nav

Some of the top-level items are getting grouped together that should stand alone. This is partially a problem with Antora as it should do more to flatten the navigation structure.

Here's the basic rules we should follow for this site:

• If a list has a title (a parent), it can have any number of top-level items
• If a list does not have a title, it should only have a single top-level item
  • Other top-level items in the same file should be defined in separate lists, forced apart using an empty block attribute list

Basically, each list should only have a single parent. That parent can either be a list title or it can be a single top-level item.

For example:

.Reference
* xref:syntax-quick-reference.adoc[]
* xref:document-attributes-reference.adoc[]

or

* xref:include.adoc[]
** xref:leveloffset.adoc[]

[]
* xref:conditionals.adoc[]
** xref:ifdef-ifndef.adoc[]

However, these two approaches still do not produce the same HTML. Since we cannot always use the first syntax (such as for single-item lists), then the second syntax should be preferred.

Add top-level Document section to nav

The document is such a foundational concept in AsciiDoc that it deserves its own top-level section in the nav. This section is the natural place for the pages about the document type and document header to live. (It's possible that the pages about document attributes could live here, though they are arguably so universal that they still deserve their own top-level section).

Here's the layout I propose:

• Document
  • Document Type
  • Document Header

Document is also a central concept in the API, so having a place to link might make writing about the API easier.

Fix scope of abstract section style

The documentation incorrectly states that the abstract style can only be applied to a section in the article doctype. The abstract style can also be used on a section in the book doctype. In this case, it becomes a chapter, even if defined as a level-0 section (in a multipart book).

Add dedicated section or page for the linenums option on source blocks

Source blocks support the linenums option. This option adds line numbers to the rendered source block when supported by the source highlighter or converter.

:source-highlighter: rouge

[source%linenums,js]
----
function fib (n) {
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

console.log([1, 2, 3, 4, 5].map(fib))
----

The linenums option can also be specified as the third positional (unnamed) attribute on the source block.

:source-highlighter: rouge

[source,js,linenums]
----
function fib (n) {
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

console.log([1, 2, 3, 4, 5].map(fib))
----

However, the named option is preferred. The option can also be enabled globally by setting the source-linenums-option attribute.

The docs should emphasize that while the option is a part of the AsciiDoc language, it does require support from the toolchain (syntax highlighter adapter, converter, and/or output format), so it may not always be honored.

The linenums option is documented in passing in the Asciidoctor docs on the page for each syntax highlighter adapter. See:

• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/pygments/
• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/rouge/
• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/coderay/

However, this topic deserves its own section or page to define it and solidify it as part of the AsciiDoc language.

Add start and end attributes for audio

I don't know whether this was known before but I discovered that audio can have start and end attributes in addition to options.

I would love to add it to the audio documentation.

Explain that the schema for block attributes and options is open-ended

Like document attributes, there's no strict schema for block attributes and options. There are a core set of reserved block attributes shared by all blocks, which includes id, role, opts, and title. There is no core set of reserved options. Certain blocks may reserve additional block attributes and define options. For example, the source block reserves the lang attribute to set the source language and the linenums option to enable line numbers. Beyond these reserved names, block attributes and options are schemaless, allowing extensions to use them for there own purpose. So really, the block attributes and options only have meaning because the processor or an extension makes use of them.

Rename formatting set to formatting pair

When we're talking about formatting marks, I think it's more intuitive to refer to them as *formatting pairs" instead of "formatting sets". A pair makes it clear there are two parts (a beginning and an end). A set does not indicate how many items, just that they belong to together.

The same update should be made when talking about constrained or unconstrained formatting marks. In fact, I would prefer the more definitive terminology "constrained formatting pair".

Move delimited blocks section to its own page

Delimited blocks are such a central concept in AsciiDoc that the topic should get its own page. Although many blocks use delimiters, not all blocks do. And we need to call attention to this difference. Additionally, the delimiters themselves have implicit meaning that we need to explain. The delimiters provide an enclosure with different basic properties (like a verbatim block or a compound block). That function is further refined by the block style.

The terminology for delimited blocks is laid out here: https://github.com/asciidoctor/asciidoctor.org/issues/223 We need to eventually cover all of these concepts, though not all of them are unique to delimited blocks.

Another description of delimited blocks can be found here: https://asciidoctor.org/docs/asciidoc-writers-guide/#delimited-blocks (though it's not as careful with the terminology)

Clearly state that source lines are normalized

When Asciidoctor reads the AsciiDoc source, the first thing it does is normalize the lines. Normalization consists of the following operations:

1. Force encoding to UTF-8 (Asciidoctor assumes the content is UTF-8 encoded)
2. Strip trailing whitespace from each line (including the end of line character)

These are performed independent of any structured context. It doesn't matter if the line is part of a literal block or a regular paragraph. All lines get normalized.

When Asciidoctor joins the lines back together to produce the rendered document (HTML, DocBook, etc), it joins the lines on the line feed character, \n.

Move docs content into docs folder

This content is being submitted as the initial contribution to the asciidoc-lang project. And since that project will have other files, these files will need to be moved into the docs folder. To make changes to that repository easier to track and cherry-pick, the docs content should be moved into the docs folder in this repository as well.

Incorrect include in the images doc

The first code example in the Images doc shows an include statement instead of the content that should be included:

Content in document.

include::example$image.adoc[tag=base] (1) (2)

Content in document

Fold intrinsic attribute reference into document attribute reference

As stated in #24, we're making an arbitrary (and sometimes incorrect) distinction between intrinsic document attributes and built-in document attributes. Let's fold the attributes listed on the Intrinsic Attributes Reference page into the Document Attributes Reference page.

The point of the Document Attributes Reference is to catalog all document attributes that are reserved / known to the processor. Many of those attributes have default or implied values. Only a handful are not meant to be changed. When those two conditions intersect, we can simply make a new section on the page to group them together. And we can use the name we're already using, "Intrinsic attributes".

Document the partintro block style in the book doctype

The language documentation never explains the purpose of the partintro block style. The partintro style marks the part intro for a part in the book doctype.

Technically, the partintro style isn't required. Any content in a book between the part title and the first chapter becomes the partintro. If the content is a paragraph, that paragraph is wrapped in an open block. The partintro style merely allows the author to make the partintro designation explicit.

The partintro style can be applied to either a paragraph or an open block. There can only be one partintro per part, and it must come immediately after the part title.

= Document Title
:doctype: book

= Part

[partintro]
This is the part intro.

== Chapter

The partintro style can only be used in the book doctype.

Document where an anchor must be placed for a description list item

The only recognized location for an anchor on a description list item is in front of the term. The documentation should state this and provide an example.

Update terminology for blocks

Terminology for delimited blocks should be as follows:

• content model - determines how the block content is processed (e.g., simple, complex, verbatim, raw)
• context - the specific function of a block (e.g., sidebar, listing, example) (aka block type)
• structural container - a given block delimiter; provides some semantic hints about how the content is handled (e.g., the content model), but is ultimately determined by the block context; each structural container has a default context (e.g., ---- is a listing)
• block name - often the same as the context, but multiple names can map to the same context, as is the case with admonition blocks and custom blocks

In general, I think we want to phase out the use of "block style". Style is very overloaded in the content domain and is easily confused with the visual appearance.

Section style should be framed as a special section

When a section title has a style, that automatically makes it a special section. The documentation should introduce the term "special section" and explain this correlation.

I also question whether we need a separate page for Dedication and Colophon. Except for a handful of exceptions, special sections are just a passthrough designation. For any special section type that AsciiDoc doesn't apply special meaning, they should be grouped on the Special Sections page and just listed. These include: colophon, dedication, acknowledgements. Though we may point out that technical the list is open ended. It's up to the discretion of the converter to handle any additional names.

Rename page for index section

The name of the page that documents the special index section is named index.adoc. However, index.adoc is typically reserved for the main page for a module or topic. Therefore, the name of the page for the special index section should be renamed. Possible names are user-index.adoc, index-section.adoc, or index/index.adoc (although the latter still uses index.adoc, it puts it under a folder that won't conflict with the main index.adoc file).

Document the full set of delimiters that can be used to make a description list

The start of a description list is identified by a term followed by a known delimiter (e.g., ::). The terms for the remaining entries at that level must use the same delimiter. The full set of delimiters that can be used to signify a term are never explicitly listed in the language docs. This fixed set of delimiters should be specified.

The delimiters are as follows:

• ::
• :::
• ::::
• ;;

Move docs for discrete headings to separate section

A discrete heading (i.e., a free-floating heading) is a unique block element, not an offshoot of section titles. Therefore, discrete headings should get their own top-level section in the docs ("Discrete Headings")*. They happen to use a similar syntax as section titles and share the marker length to heading level mapping with section titles, so this can be noted. But they are discrete elements in the document structure and cannot contain child elements. They are the closest match to headings in other markup languages such as Markdown.

* AsciiDoc Python refers to them as "Floating Titles" and DocBook refers to them as "bridgehead". We prefer the terminology "Discrete Heading". See https://tdg.docbook.org/tdg/5.2/bridgehead.html#element.db.bridgehead.6

Document the horizontal dlist in separate section

A dlist can be configured to have a horizontal arrangement. This feature is activated by adding the horizontal style.

[horizontal]
term:: description

This feature of the AsciiDoc syntax is not documented in a dedicated section, making it hard to find. It should receive just as much focus as the qanda style.

Prefer the term "link text" over "linked text"

The documentation currently uses both "link text" and "linked text" to refer to the visible text of a link. The more commonly accepted term is "link text" (as seen in CommonMark spec, the Google style guide, and elsewhere). Let's standardize on that term.

Document Index Term See and seealso

I'm excited that see and seealso landed in asciidoctor 2.0:
asciidoctor/asciidoctor#2047
asciidoctor/asciidoctor#3181

But it doesn't look like it made it into the documentation:
https://docs.asciidoctor.org/asciidoc/latest/sections/user-index/#index-terms
https://github.com/asciidoctor/asciidoc-docs/edit/main/docs/modules/sections/pages/user-index.adoc

I'm having a bit of a hard time following the commit that made the change and the thread to figure out the correct syntax.
Would someone be willing to help document that?

Document what contexts and content_model are available

Document what contexts and content_model are available because when you are writing extensions (mostly block extensions) and you are creating new blocks, you need to set which context and content_model will be assigned to that block. In extensions example it is only explained the paragraph one with simple, but there are others like pass, verbatim, raw, ... so it would be great that at extensions chapter would be an explanation of all of them.

Currently I am developing some blocks that differs from the standard one, so I can help providing examples.

Alex.

Document partial includes in quick reference

Document the partial include feature (lines and tags) in the quick reference.

Also mention that includes should be separated by a blank line unless the content being included is intended to be joined into the same block.

Create an abridged syntax quick reference

A slimmed down version of the quick reference with links to detailed sections

Document the collapsible option on example blocks

Document the collapsible option on example blocks, which transforms the block into a disclosure element (aka summary/details) in the HTML output.

Example:

.System Requirements
[%collapsible]
====
Requires a computer running an operating system.
The computer must have some memory and ideally some kind of long-term storage.
An input device as well as some form of output device is recommended.
====