Asciidoctor Community
The Asciidoctor community of projects (aka Asciidoctor Project) is a perpetual effort to develop an accessible, comprehensive, and open source toolchain and workbench for writing and publishing AsciiDoc content across various platforms and runtimes.
In addition to AsciiDoc processors for Ruby, the JVM platform, and JavaScript, the community develops plugins/add-ons for automation tools, browsers, and IDEs, as well as extended converters for producing additional output formats, adapters for expanding integrations, and extensions for augmenting AsciiDoc documents with rich media such as diagrams and charts.
The Asciidoctor community also pushes the AsciiDoc language to evolve by introducing new ideas and innovations and promotes AsciiDoc through documentation and advocacy.
Projects
The Asciidoctor Project is a loosely knit collection of projects. All Asciidoctor projects are open source (either MIT or Apache 2.0). The source repositories and issue trackers for these projects are hosted on GitHub. Each project has its own project lead(s) and maintainers (aka project team), who determine how the project is run. All contributors volunteer their time to work on a project. Asciidoctor is the primary project and, as such, provides the overall direction and vision for the community. Projects generally follow semantic versioning, though it’s not (yet) true of all projects.
Documentation
All the documentation on this site is written in AsciiDoc and published by Antora.
The source of this site is not stored in a single repository. Rather, it’s distributed across multiple repositories. This strategy is used to ensure that the content, the build, and the UI (aka theme) are not intermingled and can be managed independently. Most notably, the documentation for each project is stored alongside the project it documents. Antora aggregates the materials from all these repositories to produce a unified site.
Here’s a summary of the repositories that go into making this site.
- playbook repository (docs.asciidoctor.org)
-
Contains the build manifest that pulls all the documentation together and configures the site. The documentation content sources and UI bundle are defined in the Antora playbook file, antora-playbook.yml.
- content repositories
-
Each repository contains the documentation for the project it documents. For example, the documentation for Asciidoctor core can be found under the docs folder in the repository located at github.com/asciidoctor/asciidoctor. You can find the location of the documentation for other projects by following the “Edit this Page” link on each page. The location of these repositories is defined in the Antora playbook file.
- UI repository (asciidoctor-docs-ui)
-
Contains the UI materials (i.e., page templates, CSS, images, and scripts) and a build script that compiles them together into a UI bundle. It also hosts the released UI bundles. The location of the UI bundle is defined in the Antora playbook file.
The build of the site amounts to passing the Antora playbook file from the playbook repository to the antora command.
$ antora antora-playbook.yml
The site gets built and published nightly and on each commit to the playbook repository. If you submit a PR to the playbook repository, you will be provided with a deploy preview that includes any additional content sources you’ve added to the playbook repository. See the playbook repository for more information about how the site is built and how to build and preview it on your own machine.
Relationship to AsciiDoc
Asciidoctor serves as the reference parser/interpreter for the AsciiDoc syntax as we know it today. In other words, Asciidoctor is the official reference for how to parse and convert modern AsciiDoc.
Given this standing, Asciidoctor is inherently compliant with the AsciiDoc syntax. And Asciidoctor has evolved the AsciiDoc syntax since it took over this role from AsciiDoc.py. Yet, to continue evolving the syntax while encouraging more implementations without introducing divergence, we know we need a more formal definition for what AsciiDoc is. In other words, we need an AsciiDoc standard that’s independent from Asciidoctor.
Along with OpenDevise, the Asciidoctor project has been a driving force behind the creation of the AsciiDoc Working Group at the Eclipse Foundation. The main goal of the AsciiDoc Working Group is to oversee the creation of a formal specification for the AsciiDoc language. While Asciidoctor plans to become a compliant implementation, the specification and associated compliance program also invites other implementations to emerge. At least one such implementation will be developed under the Eclipse Foundation Development Process (EFDP). That project is Eclipse Austen, which aims to be an independent, compliant AsciiDoc processor that can run on the JVM.