Asciidoctor

New, Noteworthy, & Beyond

Logo

Processor

Asciidoctor AsciiDoc

xrefstyle

:xrefstyle: full

Refer to <<foreign-keys>>.

...

=== Foreign Keys

Refer to Section 3.2, “Foreign Keys”.

:xrefstyle: short

Refer to <<foreign-keys>>.

...

=== Foreign Keys

Refer to Section 3.2.

Translations

data/locale/attributes-<lang>.adoc

ar
bg
ca
da
de
es
fa
fi
fr
hu
id
it
ja
kr
nb
nl
nn
pl
pt
pt_BR
ro
ru
sr
sr_Latn
tr
uk
zh_CN
zh_TW

Translated attributes :: fr

:appendix-caption: Appendice
:appendix-refsig: {appendix-caption}
:caution-caption: Avertissement
:example-caption: Exemple
:figure-caption: Figure
:important-caption: Important
:last-update-label: Dernière mise à jour
...

Advanced tag filtering

Tagged include file

package com.acme;
//tag::named[]
import javax.inject.Named;
//end::named[]
import javax.enterprise.context.RequestScoped;

//tag::named[]
@Named("X")
//end::named[]
@RequestScoped
public class TheBeanCalledX {
  ...
}

Exclude all tags

----
include::TheBeanCalledX.java[tags=!*]
----

package com.acme;
import javax.enterprise.context.RequestScoped;

@RequestScoped
public class TheBeanCalledX {
  ...
}

Exclude tags by name

----
include::TheBeanCalledX.java[tags=!named]
----

package com.acme;
import javax.enterprise.context.RequestScoped;

@RequestScoped
public class TheBeanCalledX {
  ...
}

Include everything

----
include::TheBeanCalledX.java[tags=**]
----

package com.acme;

import javax.inject.Named;
import javax.enterprise.context.RequestScoped;

@Named("X")
@RequestScoped
public class TheBeanCalledX {
  ...
}

Stronger SVG support

Interactive SVG

image::diagram.svg[opts=interactive]

<object type="image/svg+xml" data="diagram.svg">
<span class="alt">diagram</span>
</object>

Inline SVG

image::diagram.svg[opts=inline]

<svg xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 600 400" version="1.1">
  <g>...</g>
</svg>

Diagrams in SVG…

[plantuml,devoxx,svg,opts=inline]
----
start
if (Going to Devoxx?) then (yes)
  : attend talks \n network \n drink beer;
else (no)
  : watch talks \n live on YouTube \n (without pants);
endif
stop
----

…means diagrams are crisp

Compliance & stability

Asciidoctor Bespoke

Basic presentation

= My Awesome Presentation

== Get Ready In...

[%build]
* 3
* 2
* 1

== Gather the Crowd

== Shout It Aloud

== Creative Cloud!

Fancy Text

[.remark%slice%fit]
== This is a  Call  to All Engineers

This is a Call to All Engineers

Performance

Why ?

GitHub AsciiDoc

35% faster!

We recognize Ruby is not the fastest language out there. Our goal has been to make Asciidoctor as fast as possible regardless. We’ve used every trick in the book to squeeze performance out of Ruby, and it has paid off.

Asciidoctor 1.5.6 is 35% faster than 1.5.5. In total, that makes Asciidoctor 100 times as fast as AsciiDoc.py.

One trick we use is to only run regular expressions or other expensive matchers on a string if it’s even possible a match will occur. Another trick is to simply upgrade Ruby. And we still have some other tricks up our sleeve.

So why the focus on performance? Asciidoctor must process a ton of documents, and that can have a significant impact on the turnaround time of CI and CD. Dan recently worked with a project that required over 5,000 AsciiDoc files to be processed in a single build. While it would take AsciiDoc Python an entire work day to build it, Asciidoctor is able to do it in under 5 minutes. As you can see, performance has a real impact on workflows in the real world.

Also, the faster Asciidoctor runs, the sooner writers can see a preview of the document in a local editor. In fact, optimal performance of the processor is incredibly important to the diverse integration and extension ecosystem that depends on core. So you can be sure we check every commit going into master to ensure it doesn’t degrade performance.

Ecosystem

gem download chart — Source: http://bestgems.org/gems/asciidoctor

Gem 2.5m

AsciidoctorJ 0.5m/y

Asciidoctor.js 35.5k

Repositories 70

Contributors 376

Supporters 80

AsciidoctorJ

Inline issue macro

# ex. issue:48[]
Asciidoctor::Extensions.register do
  inline_macro :issue do
    process do |parent, id, attrs|
      base_uri = parent.document.attr 'uri-issues'
      create_anchor parent, id, \
          type: :link,
          target: "#{base_uri}/#{id}",
          attributes: attrs
    end
  end
end

Inline issue macro

// ex. issue:48[]
asciidoctor {
  extensions {
    inline_macro (name: 'issue') { parent, id, attrs ->
      baseUri = parent.document.getAttribute('uri-issues')
      createInline(parent, 'anchor', id, attrs, [
        type: ':link',
        target: "${baseUri}/${id}".toString(),
        attributes: attrs
      ])
    }
  }
}

Asciidoctor.js

Asciidoctor.js is particularly important because it sits at the center of the tooling ecosystem. In particular, it provides in-application previews of the document, rendered directly in the browser, which is seen in the Atom plugin, the Brackets plugin, the Chrome/Firefox/Opera extension, docgist, and AsciidocFX. It’s also used in several Node-based static site generators. More on that later.

Here’s what’s new:

Asciidoctor.js is now on par with core; there is no reduction in functionality
The latest release brings full Unicode support, which was a critical step in matching the capability of core
It also offers a porcelain API (core & extension), which abstracts away method signatures left behind by Opal
In fact, Asciidoctor.js provides full access to core and its extension points, so you can write extensions in JavaScript.

Inline issue macro

# ex. issue:48[]
Asciidoctor::Extensions.register do
  inline_macro :issue do
    process do |parent, id, attrs|
      base_uri = parent.document.attr 'uri-issues'
      create_anchor parent, id, \
          type: :link,
          target: "#{base_uri}/#{id}",
          attributes: attrs
    end
  end
end

Inline issue macro

// ex. issue:48[]
Opal.Asciidoctor.Extensions.register(function () {
  this.inlineMacro('issue', function () {
    this.process((parent, id, attrs) => {
      const baseUri = parent.getDocument()
          .getAttribute('uri-issues')
      return this.createInline(parent, 'anchor', id, {
        type: 'link',
        target: `${baseUri}/${id}`,
        attributes: attrs
      })
    })
  })
})

Adoption

In August, Fedora announced it was switching from DocBook to Asciidoctor. That initiative was sparked in part by a talk Dan gave about Asciidoctor at the Fedora User and Developer conference more than 4 years ago.
In fact, you can find Asciidoctor used all across Red Hat. There are personal reasons why this is particularly meaningful to Dan.
The Java EE leadership recently announced that the Java EE tutorial has been rewritten in AsciiDoc and processed by Asciidoctor.
Vogella does all its tutorials and trainings in Asciidoctor.
The Khronos Group uses Asciidoctor for its Vulkan manual.
Vogella and The Khronos Group are notable for provide funding for the project, as do many of the core contributors.
Matt Raible, who needs no introduction, wrote the JHipster MiniBook in AsciiDoc and converted to PDF for download and print using Asciidoctor PDF.
Thorben Janssen, author of the thoughts-on-java blog, wrote his Hiberate Tips book in AsciiDoc and converted it to an ebook for self-publishing using Asciidoctor EPUB3.

There are too many users to mention here. If you search, you’ll quickly be able to find many more.

Future

Semantic versioning

Our experience in the past few years, especially as the Asciidoctor ecosystem grows, has made it painfully obvious that we need to shift to semantic versioning.

{slide} The time between releases is too long and each micro release of Asciidoctor core is like a major release, so there’s no room for anything else. We need to make room. We also need to move away from a single version scheme across the ecosystem. We’ll be much better off if projects themselves are versioned semantically and we then track compatible versions.

A shift to semantic versioning should also allow us to release faster. The minor stuff can go through without getting held up by the major stuff.

{slide} The initial goal of Asciidoctor was to serve as a drop-in replacement for AsciiDoc.py. Therefore, we decided to mirror the HTML it produced, as eccentric as it was. But we always knew we’d eventually need switch to producing HTML that is more semantic and easier to style with CSS. That time is upon us.

{slide} In fact, that transition is already underway. When we made the HTML for the EPUB3 converter, we experimented with how AsciiDoc mapped to a semantic HTML structure. We also did the same for the Bespoke converter. Inspired by that work, Jakub Jirutka has put together a template-based converter named html5s that produces semantic HTML5 output. You can use all of those today. The final step is to fold all this work into core and make it the default converter.

{slide} Another feature users often ask about is validation. We had always planned on adding validation of AsciiDoc to the processor. When Dan started working on it in a recent contract, he realized that validation doesn’t belong in the processor. The needs of the processor are just very different from the needs of a validator. A validator needs to keep track of where every character is in the original source so it can give exact details, offsets, and perhaps even to fix the problem. The processor only cares about the effective value and general information about context for reporting. So we needed a validation system.

{slide} This is where textlint comes in. textlint builds on the popularity of eslint. First, you implement a parser for the language, which we’ve started to do. The parser currently only handles blocks, but we’re going to (finally) take a crack at parsing inline nodes like formatted text and macros.

What we’re hoping will come out of this effort is a strategy for making an inline parser for core, which has long been its Achilles heal. The regular expression-base approach has brought us a long way, but we’re reaching its limits and it’s time to get formal.

{slide} Once the document is parsed, then you write rules that listen for nodes and look for things to validate. For example, if you wanted to check for insecure URLs, you could listen for all paragraph nodes and only check for URLs in those regions, thus skipping any verbatim blocks.

{slide} As you can see, you get exact line number and character offsets in the message.

Once this system is ready, you have much more control over what is validated. We’ll likely provide a core set of rules, but you can also write your own.

{slide} I’m very excited to to talk about a new open source project OpenDevise has been working named Antora that will impact the future of Asciidoctor. Over the last couple of years, OpenDevise has been studying documentation systems in the field. They noticed that, although there are tons of static site generators available, few, if any, are well-suited for documentation sites, more specifically AsciiDoc-based documentation sites. Antora is designed exactly for that use case.

Antora is an open source, modular Asciidoctor documentation toolchain and workflow for technical writing teams to create, manage, collaborate on, remix, and publish documentation sites sourced from a variety of versioned content repositories without needing expertise in web technologies, build automation, or system administration.

{slide} Unlike most static site generators, Antora does not assume content is all in one place. Instead, it goes out and clones content repositories and plucks files from branches of those repositories. It then integrates deeply with Asciidoctor to generate the pages and the navigation.

{slide} Although what Antora does is complex, it’s driven by a simple configuration file called a playbook. This file describes at a high level what needs to be done Where’s the source, where’s the output, what settings should be used.

The goal with Antora is to make documentation sites easy to create, simple to manage, and fun to work on. And it provides a real world use case for us to improve Asciidoctor. Antora uses Asciidoctor.js, so it’s going to have a strong impact on that project in particular.

You can learn more about Antora and follow along with development at gitlab.com/antora. OpenDevise is working on a series of posts that introduce the project and explain the problem we’re trying to solve with it.

{slide} Documentation is our game, so we end our story where we began.

{slide} The Asciidoctor user manual has received considerable contributions over the past year, especially from Rocky Allen and Andrew Carver. The manual remains the best place to get accurate and up-to-date information about the AsciiDoc syntax and Asciidoctor capabilities.

While it provides great raw material, it needs to be overhauled. That’s where Antora comes in. We’re going to drink our own beer and use Antora for the Asciidoctor documentation. Not only will this bring some spring cleaning to the content that’s already there, it will also address the problem that asciidoctor.org only really talks about core processor. There are a few pages here and there about other projects in the ecosystem, but they are mostly isolated and one-pagers. By using Antora, we can shift the documentation for the projects back to the project repositories and then consume them when the site is built. It’s really the exact case for which Antora was designed, so it’s a chance to see it in action. It will also help us improve Antora by applying it to another real world scenario.

{slide} So the future is both Asciidoctor and Antora. We want to love writing our docs as much as users love writing theirs.

{slide} Thank you!

Semantic HTML

asciidoctor html5s — https://github.com/jirutka/asciidoctor-html5s

Validation

textlint :: insecure-url-rule

const LinkMacroRx = /(http(s)?:\/\/[^\[]+)\[[\s\S]*?\]/g
module.exports = ({ RuleError, report }) => ({
  'ParagraphNode': (node) => {
    node.children.forEach((line) => {
      let match
      while ((match = LinkMacroRx.exec(line.raw)) != null) {
        if (match[2] != null) continue
        report(line, new RuleError(
          `Illegal link to a non-secure URL: ${match[1]}`,
          { index: match.index }))
      }
    })
  }
})

$ textlint "**/*.adoc"

server-docs/modules/ROOT/content/user-manual.adoc

  14:124  error  Illegal link to a non-secure URL:
                 http://example.com (non-secure-url)

✖ 1 problem (1 error, 0 warnings)

Antora

I’m very excited to to talk about a new open source project OpenDevise has been working named Antora that will impact the future of Asciidoctor. Over the last couple of years, OpenDevise has been studying documentation systems in the field. They noticed that, although there are tons of static site generators available, few, if any, are well-suited for documentation sites, more specifically AsciiDoc-based documentation sites. Antora is designed exactly for that use case.

Antora playbook

site:
  url: https://docs.example.com
  title: Docs Site
content:
  sources:
  - url: https://github.com/acme/solution-docs.git
  - url: /home/username/projects/server-docs
    branches: [ v2.5, v3.0, v3.1 ]
  - url: git@github.com:acme/api-gateway-docs.git
    branches: v2*

Documentation

The Asciidoctor user manual has received considerable contributions over the past year, especially from Rocky Allen and Andrew Carver. The manual remains the best place to get accurate and up-to-date information about the AsciiDoc syntax and Asciidoctor capabilities.

Antora Asciidoctor

Thank You!

asciidoctor.org

Logo

Processor

Asciidoctor AsciiDoc

xrefstyle

:xrefstyle: full

:xrefstyle: short

Translations

data/locale/attributes-<lang>.adoc

Translated attributes :: fr

Advanced tag filtering

Tagged include file

Exclude all tags

Exclude tags by name

Include everything

Stronger SVG support

Interactive SVG

Inline SVG

Diagrams in SVG…​

…​means diagrams are crisp

Compliance & stability

Asciidoctor Bespoke

Basic presentation

Fancy Text

Performance

Why ?

GitHub AsciiDoc

35% faster!

Ecosystem

AsciidoctorJ

Inline issue macro

Inline issue macro

Asciidoctor.js

Inline issue macro

Inline issue macro

Adoption

Future

Semantic versioning

Semantic HTML

Validation

textlint :: insecure-url-rule

Antora

Antora playbook

Documentation

Antora Asciidoctor

Thank You!

Diagrams in SVG…

…means diagrams are crisp