AsciidoctorJ 1.5.0 released!

by Alex Soto -

We’re thrilled to bring the latest Asciidoctor milestone, Asciidoctor 1.5.0, to the JVM as AsciidoctorJ 1.5.0!

What is AsciidoctorJ?

AsciidoctorJ is the official library for using Asciidoctor on the JVM. With AsciidoctorJ, you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from Java and other JVM languages.

Resolved Issues

The following issues have been resolved in version 1.5.0:

  • Added methods to register extensions to AsciidoctorJ which can be written in Ruby or Java. Resolves #90 and #157.

  • Creates an SPI so Java extensions can be registered automatically by simply adding the jar inside classpath. Resolves #97

  • Extension API is updated with modifications done in Asciidoctor 1.5.0. Resolves #113, #114, #148, #162 and #166.

  • Provides a method to unregister any extension previously registered. Resolves #122

  • Added -r and -I flags to CLI classes to require additional Ruby scripts and append to the load path, respectively. Resolves #171.

  • Added -V and --version flags to CLI classes. Resolves #87 and #117.

  • Adds integration with the Asciidoctor EPUB3 project. You can set epub3 as a backend. Resolves #168 and #179

  • Updates AbstractBlock class with findBy method. Resolves #164

  • Updates Document class to be aligned with Asciidoctor::Document so getting a title can return a Title class with title, subtitle instead of as String with full title. Resolves #167

  • Promotes attributes sectnumlevels, hardbreaks, appendix-caption, stem, hide-uri-schema, nofooter, source-language and compat-mode. Resolves #91, #92, #94, #105, #121, #129, #144 and #163.

  • You can get the Ruby instance used in AsciidoctorJ from JRubyRuntimeContext class. Resolves #93

  • Fixes a bug with Ruby instance and Attributes class which prevented the Gradle plugin from working properly. Resolves #96

  • Skips files and directories that begin with an underscore (_) in AsciiDocDirectoryWalker. Resolves #124

  • Adds slf4j as logging system. Resolves #126

  • Fixes a bug with base_dir and Ruby environment. Resolves #135

  • Document objects like Section, Block, Node, Document, …​ are moved to the org.asciidoctor.dom package.

  • Updates Java version to Java 7. Resolves #176

For more information about issues fixed in this release, please see the 1.5.0 milestone in the issue tracker!

Migration

The artifactId changed from asciidoctor-java-integration to asciidoctorj starting in 1.5.0. You should now use the following dependency stanza in your project’s pom.xml file:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.0</version>
</dependency>

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content. We also encourage you to browse the release notes for Asciidoctor 1.5.0.

Asciidoctor 1.5.0 introduced many changes internally and to the public API. For example, the extension API has been modified in non-trivial ways, so you’ll like need to update your extensions to the new API when upgrading to this release of AsciidoctorJ.

Visit the updated AsciidoctorJ manual to learn how to install and use AsciidoctorJ.

This release makes way for new releases of the Gradle plugin, Maven plugin and Asciidoclet, all of which are based on AsciidoctorJ. Look for those announcements to follow!

Asciidoctor 1.5.0 “Bleeding Heart” released!

by Dan Allen and Sarah White -

The long-awaited release of Asciidoctor 1.5.0 “Bleeding Heart” has arrived at last! This release includes a stockpile of 150 fixes, improvements and enhancements as well as several refinements to the AsciiDoc syntax. We’re confident you’re going to love writing with Asciidoctor more than ever before.

Asciidoctor 1.5.0 is the sequel to 0.1.4. We shifted the numbers to adopt a semantic versioning scheme and communicate that this release is well beyond stable.

Please take note!

Before you upgrade to Asciidoctor 1.5.0, it’s important to know we’ve introduced some changes to the AsciiDoc syntax that aren’t backward compatible. Don’t panic, though! We also introduced a compatibility mode.

Refer to the migration guide for information about the affected syntax and how to migrate (or prepare to migrate) your content. By making these syntax changes, we’re working to make AsciiDoc more consistent and easier to learn.

Milestones & momentum

We closed 150 issues during the Asciidoctor 1.5.0 development cycle. At the time of the last release, we announced that Asciidoctor had reached 50,000 downloads from RubyGems.org. This time around, we didn’t just double the download count, we quadrupled it! Asciidoctor has now been downloaded more than 225,000 times at the time of this release!

It’s not the download count of which we’re most proud. It’s the community of awesome people . There are now over 50 contributors in the Asciidoctor ecosystem, and this release alone has received participation from nearly every person in this group! If you haven’t had a chance to participate in Asciidoctor, there’s never been a better time to join in.

Here’s a summary of the milestones we’ve crossed:

  • 150 issues closed in 1.5.0

  • 50 total contributors

  • 225,000 total downloads

  • 1,800 total commits

  • 1,500 tests

  • 1000 total issues (including pull requests)

  • 800 issues closed in total (including pull requests)

  • 400 mailing list topics

  • 2 years of development (initial commit Jun 1, 2012)

This wouldn’t be an Asciidoctor release announcement without discussing the speed of the processor. The 1.5.0 release brings another 10% improvement in speed over the previous version. To give you a picture of how fast it is now, the Spring Framework Reference Guide, weighing in at 50,000+ lines, renders to HTML in 1.15 seconds on an Asus ZenBook UX301LA using Ruby 2.1.

Asciidoctor is now in use by even more open source projects, including Groovy, Griffon, GroovyFX, Infinispan, Weld, Hibernate OGM, Spring Data and git-scm.com. It’s also used to produce NFJS, the Magazine. Best of all, Sarah has been hard at work filling in Asciidoctor’s own user manual and helping teams understand how to write better documentation.

In case you didn’t notice, the Asciidoctor project is on . On that note, let’s get to what’s in this new release!

Release highlights

Get technical with MathJax

If you need to get technical in your writing, Asciidoctor integrates with MathJax to allow you to write TeX / LaTeX or AsciiMath expressions directly in your document.

A typeset LaTeX math equation
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}\]

With a simple declaration of the stem attribute, you can now write inline and block formulas in plain text too!

Diagrams, diagrams, diagrams

You can add even more visual elements to your document with diagrams conjured from plain text. Asciidoctor Diagram emerged from a request to port the PlantUML extension for AsciiDoc Python to Asciidoctor. Pepijn Van Eeckhoudt (@pepijnve) took the reins and created a comprehensive diagram extension that not only adds integration with PlantUML, but three additional diagramming tools, as well as a framework for adding more in the future.

Asciidoctor Diagram 1.5.0 now supports the following diagramming tools:

Asciidoctor Diagram process diagram

See the Asciidoctor Diagram guide to learn how to create diagrams from ASCII art in your AsciiDoc documents.

Curious how to load extensions like Asciidoctor Diagram from the commandline interface? Read on.

Load extensions from the CLI

Asciidoctor introduced an extensions API in 0.1.4 that enables you to extend the AsciiDoc syntax and tap into the lifecycle of the processor. However, it was only possible to load these extensions when invoking Asciidoctor via the API or by creating a custom launch script.

The asciidoctor command now supports the -r and -I flags (ported from the ruby command) to require additional paths or modify the load path, respectively.

Here’s an example of how to use the -r flag to enable the Asciidoctor Diagram extension:

$ asciidoctor -r asciidoctor-diagram sample.adoc

The -r flag also accepts absolute or relative paths and can be used multiple times.

$ asciidoctor -r ./my-extension-a.rb -r ./my-extension-b.rb sample.adoc

The scripts referenced by the -r flag are loaded in the order they are listed before any other processing occurs.

Now you get the full power of the asciidoctor command plus extensions!

Embracing DocBook 5

The DocBook 5 specification was finalized in 2008. It’s time we embrace it.

DocBook 5 is now the default output when you use the docbook backend. If you still need to produce DocBook 4.5, use the docbook45 backend.

Making XML parsers happy

HTML5 reintroduced flexible HTML syntax that’s only loosely based on SGML…​and most certainly not XML. This decision makes HTML5 more approachable. However, it makes XML parsers .

To accommodate tools that use XML parsers to read the generated HTML, Asciidoctor can now output the XHTML variant of HTML5, known as XHTML5.

To output XHTML5 instead of HTML5, set the backend to xhtml or, to be more explicit, xhtml5. The “x” at the beginning of the name cleverly tells Asciidoctor to close short tags, assign values to boolean attributes and add the xmlns attribute to the root element.

Trust us, your XML parser will thank you.

PDF and EPUB3

Asciidoctor can now convert directly from AsciiDoc to PDF and EPUB3, using Asciidoctor PDF and Asciidoctor EPUB3, respectively. These converters are hosted in their own repositories and are distributed as separate gems.

EPUB3 generated by Asciidoctor EPUB3

The converters are currently alpha, but still very functional.

Asciidoctor.js is Asciidoctor

Guillaume Grossetie (@mogztter) led the effort during the 1.5.0 development cycle to align the Asciidoctor.js code base with Asciidoctor core. After a lot of fiddling and Opal patches, Asciidoctor.js now builds directly against master and the Asciidoctor 1.5.0 release. That means that for the first time, Asciidoctor.js is Asciidoctor.

Anthonny Quérouil (@anthonny) followed up by developing a Grunt build script to bundle Asciidoctor.js and publish it to npm (the Node.js package manager) and Bower (the web package manager).

Guillaume is the creator of the AsciiDoc preview for Chrome and Anthonny the creator of the AsciiDoc preview for Atom. The AsciiDoc preview for Atom complements the AsciiDoc language definition kicked off by Anton Moiseev (@antonmoiseev). Thomas Kern (@nerk) was quick to follow up with an AsciiDoc plugin for Brackets based on the aforementioned work. We also invited the veteran project of Asciidoctor.js, DocGist, into the Asciidoctor organization. DocGist was created by Anders Nawroth (@nawroth). Guillaume, Anthonny, Anders, Thomas, Anton and others have been collaborating on tooling based on Asciidoctor.js. They’re helping Asciidoctor boldly go where no AsciiDoc implementation has gone before.

The alignment of Asciidoctor.js with Asciidoctor core was a major effort. I want to sincerely thank Guillaume, Anthonny and the Opal team (Adam Beynon, meh and Elia Schito) for making this happen.

AsciiDoc syntax shuffle

The single quote (') and the backtick (`) are two markup characters in the AsciiDoc syntax that often give people trouble. They like to get in each other’s way. We decided to shuffle some of the AsciiDoc syntax to address this problem and, in general, make it more consistent and easy to learn. Not only do these changes reduce slip ups by the parser, they also strengthen the meaning of the plus character and bring more alignment with Markdown by making the backtick the primary character for monospace formatting.

Migrating with compat-mode

Before introducing what’s changed, we want to emphasize that you can forgo the italic, monospace and passthrough syntax changes by setting the compat-mode attribute, shown here defined in the document header:

:compat-mode:

or by using a two-line document title:

Document Title
==============

Compat mode is used to enable legacy syntax when the new syntax deviates from it. See the migration guide for more information about migrating your AsciiDoc documents and the transitional syntax that’s available.

“+” means passthrough

The + character in the original AsciiDoc syntax is not used consistently. Single plus (+) and double plus (++) are used to format text as monospace, whereas triple plus (+++) and quadruple plus (++++) are used to escape text from processing.

We made AsciiDoc more intuitive and easier to teach by always using + as a passthrough formatting mark. Instead of using the single plus and double plus for monospaced formatting, we’ve made them constrained and unconstrained literals (i.e., “render it as it looks”), respectively. For example:

+_bar_+ becomes _bar_
foo++_bar_++ becomes foo_bar_

We haven’t yet mentioned how to format text as monospace. For that, we’ll put the backtick back into play.

Markdown-style monospace

Authors who are familiar with Markdown are accustomed to using the backtick (`) to format text as monospace. We’ve embraced this convention in Asciidoctor.

Using backtick characters around text now means the text should be formatted as monospace only. The backtick characters do not add passthrough semantics, as they did before. In most cases, the passthrough semantics aren’t necessary, so using the backticks for monospaced formatting is sufficient.

`literal` becomes literal (in monospace)
`{backend}` becomes html5 (in monospace)
a``||``b becomes a||b (where || is monospace)

If you want to prevent substitutions in the monospaced text, just remember, “plus for passthrough”:

`+{backend}+` becomes {backend} (in monospace)

By not mixing monospace formatting with passthrough (literal) semantics, we are deviating slightly from the behavior of backticks in Markdown. However, that’s because AsciiDoc has additional features, such as attribute references, that we want to be able to leverage when formatting text as monospace.

There will be a period of time during which you’ll have to process your document with both Asciidoctor 0.1.4 and 1.5.0 (mostly while we wait on GitHub to upgrade). We’ve added special logic in the processor to handle a hybrid syntax to use in the interim. Please refer to the migration guide for details.

Smarter “smart” quotes

Legacy AsciiDoc also uses the backtick character for making curved quotes. Because the syntax was so similar to that of monospaced literal text, it often matched in unexpected ways. We’ve made the smart quotes syntax…​smarter.

In Asciidoctor 1.5.0, the backtick acts as a modifier on a quote to indicate it should be curved. You now place the backtick inside the quote character, adjacent to the quoted phrase, to make it “smart”.

Dig through a copy of '`The Times`' and you're bound to see a lot of "`smart`" quotes.

This change brings the backtick closer in proximity to the quote and thus makes parsing more deterministic. See the user manual for more curved quote and apostrophe examples.

Quote means quote

Single quotes around a phrase are now left alone unless you’re running Asciidoctor in compat mode.

AsciiDoc traditionally supported single quotes as an alternate syntax for marking a phrase as italic. However, single quotes around a phrase already have a very well-defined meaning in Western languages. Making them something they aren’t just isn’t a good idea. We never recommended them for this purpose anyway. Furthermore, they conflict with the new curved quote syntax, so they had to go.

Refer to the migration guide to help ensure a smooth transition to the new syntax.

Level your offsets

The leveloffset attribute is used to shift the level of sections when combining documents. It works great for a single include level, but as Groovy developers Cédric and Guillaume discovered, it quickly breaks down when you get into multiple levels of nesting.

The problem is that the level offset value is assumed to be absolute. Asciidoctor now supports relative level offset values using a leading + or - operator.

:leveloffset: +1
include::chapter-01.adoc[]
:leveloffset: -1

Alternatively, you can specify the leveloffset attribute directly on the include directive so you don’t have to worry about restoring the old value.

include::chapter-01.adoc[leveloffset=+1]

Filtered tag directives

The Groovy developers use the include and tag directives a lot. They discovered that tag directives within a broader tagged range get carried over into the document. Asciidoctor now drops these lines so you can nest fine-grained ranges within broader ranges.

The tag directives are also searched using a more strict match to avoid false matches.

Substitution modifiers

When you needed to customize the substitutions on a block, you used to have to list out all the substitutions you wanted to enable. It’s now possible to add or remove substitutions to the default substitution set using the + and - modifiers (e.g., [subs=+quotes]). That should save a lot of unnecessary typing!

Secure assets

Serving assets over SSL is a best practice to avoid man-in-the-middle attacks and preying eyes in general.

All remote assets referenced out of the box in Asciidoctor, such as Font Awesome, are now served over SSL from https://cdnjs.cloudflare.com and https://fonts.googleapis.com.

Hide the URI scheme

Asciidoctor auto-detects and auto-links URLs. Writers often don’t take advantage of this feature because the link shows the URI scheme prefix (e.g., http://). So, they end up long-handing it for the sole purpose of hiding the prefix.

https://asciidoctor.org[asciidoctor.org]

Now, Asciidoctor can produce the exact same result if you set the hide-uri-scheme attribute on the document.

:hide-uri-scheme:

https://asciidoctor.org
Rendered URL when hide-url-scheme is set

asciidoctor.org

Human-friendly cross references

If you’re linking to an anchor point somewhere else in your document, you can refer to it by title instead of by ID.

Refer to <<Section A>>.

== Section A

You’ll likely want to switch to using IDs as the document matures, but this should certainly help with flow in early drafts!

Print your docs

Leif Gruenwoldt (@leif81) pointed out that the print styles were too aggressive, causing the printed document to lose its integrity. We worked together to tweak the stylesheet until the output looked nearly as good as the PDF generated by the DocBook toolchain. The styles even separate chapters into different pages when using the book doctype. In addition to these styles, we also added the missing table border styles for all the grid and frame permutations on both web and print.

Who needs DocBook when you’ve got HTML5 and CSS3?

Print preview of HTML generated by Asciidoctor

Open Source fonts

The culture of Asciidoctor is deeply rooted in Open Source, so we want to be Open Source all the way down.

In the past, the default stylesheet relied on Microsoft Core Fonts (Arial and Georgia) installed on the user’s system. We’ve replaced these proprietary fonts with Open Source fonts, which we load from Google Fonts.

Here are the fonts we’ve selected:

  • Noto Serif - prose and block titles

  • Open Sans Light - section headings

  • Droid Sans Mono - monospaced text and preformatted blocks

We particularly like Noto Serif because it’s an extremely readable font and it supports all the world’s languages.

We made additional refinements to the default stylesheet that give it a professional, modern appearance. Here’s a preview of the new default theme:

Screenshot of default Asciidoctor theme

Font Awesome 4.1

Speaking of fonts, Asciidoctor integrates with Font Awesome 4.1, thanks to the work done by Guillaume Grossetie (@mogztter)! You now have over 400 icons available to accessorize your document!

Many icons were renamed in Font Awesome 4. If you have existing documents that use the icon macro, you may want to add the Font Awesome 3 compatibility CSS that Guillaume created to ease the transition.

“Everything is AWESOME!!!”

Acknowledgments

The best part of Asciidoctor is, and will always be, its thriving community. We’d like to thank the following people for participating in this release.

We’d like to give special shout outs to the following people:

  • to Guillaume Grossetie, Ken Dreyer, Leif Gruenwoldt, @megathaum, Ken Finnigan, Brian Carlson, Aslak Knutsen, David Gamba, Wim Champagne, Charles Moulliard, Jean-Louis Jouannic, Roman Priesol and James FitzGibbon for making their first source contributions to Asciidoctor core.

  • to Guillaume Grossetie for spearheading the effort to align Asciidoctor core and Asciidoctor.js.

  • to Anthonny Quérouil for setting up a Grunt build for Asciidoctor.js and getting it published to npm and Bower.

  • to members of the Opal team (Adam Beynon, meh and Elia Schito) for helping us achieve compatibility with Opal and making necessary upstream changes.

  • to Ken Dreyer for overhauling the RPM package for Fedora and upgrading the Asciidoctor test suite to Minitest 5.

  • to Peter Neubauer for making the very first Asciidoctor t-shirt, which I wore for the release!

I (Dan) would also like to thank Sarah White for her monstrous effort providing input into the software design, editing the user manual, updating the website, testing (read as: breaking) and establishing a documentation workflow for the project. Asciidoctor would not be what it is today without her dedication.

Additional thanks to everyone who is using the project, advocating for better documentation and those who have participated in the growing ecosystem of sub-projects. The mission of Asciidoctor is to help you write, publish and communicate your content successfully, and enjoy doing it! With your feedback and participation, we can achieve that goal together! We encourage you to ask questions and discuss any aspects of the project on the mailing list, Twitter or IRC.

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. We’re always eager to learn about your experiences and how we can help improve them. Together, we’re making documentation fun, easy, and rewarding!

What’s next?

This release is just the beginning of the release train. Look for releases of AsciidoctorJ, Asciidoctor.js, the build plugins (Gradle and Maven), the Linux packages and more!

The next release of Asciidoctor will be the 1.5.1 point release. From now on, we plan to iterate much faster and only do announcements for major and minor versions.

See the CHANGELOG for a complete list of changes.

Plain-text diagrams take shape in Asciidoctor!

by Pepijn Van Eeckhoudt -

You write in plain text. You code in plain text. How about creating diagrams in plain text too? Now you can using Asciidoctor Diagram!

Introduction

Asciidoctor is a fantastic tool to use when writing technical documentation. It allows you to spend more time focusing on your content rather than struggling with WYSIWYG tools.

One task that still pulls your focus away, and is more difficult than it should be, is integrating technical diagrams into your documents. It involves launching a UML or diagramming tool, pushing pixels around the screen to draw the diagrams, exporting the result to a web-friendly image format and linking to them from your source document. The many benefits that AsciiDoc provides in terms of visual consistency, ease of collaboration, etc. are not available when you are working with diagrams.

All that changes today with the announcement of the Asciidoctor Diagram extension. Asciidoctor Diagram integrates existing plain text syntax diagramming tools into the Asciidoctor processing. That means you can embed the source code for your diagrams directly into your documents!

The first version of Asciidoctor Diagram supports the following diagram languages:

These “lightweight diagram languages” are to graphical diagrams what AsciiDoc is to HTML. Another way of saying it:

language analogy diagram

Your first plain-text diagram

The simplest way to add diagrams to your documents is by using diagram blocks. Just add a listing block to your file using the appropriate syntax name (ditaa, graphviz or plantuml) as the block name (aka style).

[ditaa]
----
                   +-------------+
                   | Asciidoctor |-------+
                   |  Diagram    |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /----------------\
 |        | --+ Asciidoctor +--> |                |
 |  Text  |   +-------------+    |Beautiful output|
 |Document|   |   !magic!   |    |                |
 |     {d}|   |             |    |                |
 +---+----+   +-------------+    \----------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
----

When the Asciidoctor Diagram extension processes this type of block, it will read the body of the block, pass it to the ditaa library, write the resulting image to disk and generate an image block. Here’s how it appears in the rendered document:

sample ditaa diagram

Magic!

Generating one of these images is fairly quick, but if you start adding lots of diagrams to your document the processing time can start adding up. Asciidoctor Diagram optimizes the processing by keeping track of diagram metadata in *.cache files and will only regenerate the images if the diagram source code was modified. This keeps incremental rendering of documents a speedy process.

Controlling the output

By default Asciidoctor Diagram creates PNG images and calculates an output file name automatically based on the diagram source code. This behavior can be overridden using the target and format attributes. You can specify these attributes as the first and second positional attributes or as explicitly named attributes. An SVG file with a specific name a Graphviz diagram can be generated as follows

[graphviz, dot-example, svg]
----
digraph g {
    a -> b
    b -> c
    c -> d
    d -> a
}
----

After the magic happens, you’ll see:

sample graphviz diagram
Asciidoctor Diagram bundles both the ditaa and PlantUML libraries and will use them to generate diagrams. In order to generate diagrams using Graphviz, you must install it separately (meaning the dot command must be available on your PATH).

Asciidoctor Diagram turns the diagram blocks into image blocks and applies any additional attributes. This means you can use the normal Asciidoctor facilities to control the positioning of the generated image. Block titles and IDs can also be assigned in the same way.

[[main-classes]]
.The PlantUML block extension class
[plantuml, sample-plantuml-diagram, alt="Class diagram", width=135, height=118]
----
class BlockProcessor
class PlantUmlBlock
BlockProcessor <|-- PlantUmlBlock
----

Here’s what gets rendered:

Class diagram
The PlantUML block extension class

Including external diagrams

It might not always be desirable to embed the source code for diagrams in your document. External diagrams can also be processed using the block macro syntax. This is very similar to how you typically include images in your documents.

plantuml::classes.txt[format=svg, alt="Class diagram", width=300, height=200]

Enabling the extension

Asciidoctor 0.1.4 does not yet allow extensions to be enabled via the command line. That is a feature coming in Asciidoctor 1.5.0. Until then, the easiest way to enable the extensions is to use a short wrapper script. The following script, asciidoctor-diagram, loads and registers the Asciidoctor Diagram extension, then invokes Asciidoctor in the same way as the asciidoctor command.

asciidoctor-diagram launch script
#!/usr/bin/env ruby

require 'asciidoctor' (1)
require 'asciidoctor/cli/options'
require 'asciidoctor/cli/invoker'

require 'asciidoctor-diagram' (2)

invoker = Asciidoctor::Cli::Invoker.new ARGV (3)
invoker.invoke!
exit invoker.code
1 Loads Asciidoctor
2 Loads and registers the Asciidoctor Diagram extensions
3 Invoke the Asciidoctor CLI

Put the asciidoctor-diagram script on your PATH, make it executable and use it in place of the asciidoctor command.

$ asciidoctor-diagram my-doc-with-cool-diagrams.adoc

After running the asciidoctor-diagram script on your document, go check out the cool diagrams it made for you!

Go play!

Now it’s time to go play with Asciidoctor Diagram. Explore what you can do with it and how it can be improved. To help you get started, check out these examples in the Asciidoctor Diagram repository. We look forward to hearing from you on the Asciidoctor discussion list or the Asciidoctor Diagram issue tracker.

Together, we can make diagrams and documentation come to life out of plain ol' text!

5 things to know about the GitHub Asciidoctor upgrade

by Dan Allen -

After much anticipation, GitHub recently upgraded Asciidoctor to the 0.1.4 release, thanks to @bkeepers!

Even bigger news than the upgrade, syntax highlighting is enabled in source listings! If you need to see it to believe it, I present you proof.

syntax highlight sample github
Figure 1. Syntax highlighting in an AsciiDoc source block on GitHub

Since much has changed in Asciidoctor since version 0.1.0—​the previous version deployed—​we’ll look at 5 things to know about this upgrade to make the most of AsciiDoc rendering on GitHub.

1. Source code syntax highlighting

First and foremost, syntax highlighting of source code is finally enabled! The splashes of color in the source listings are added by the Pygments syntax highlighter.

You don’t have to do anything special to start using this feature. Just add a source block to your AsciiDoc file using:

  1. the listing block syntax

    [source,ruby]
----
puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item|
  "I use #{item}!"
} * "\n"
----

  2. the open block syntax

    [source,ruby]
--
puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item|
  "I use #{item}!"
} * "\n"
--

  3. or the fenced code block syntax (ala GitHub-flavored Markdown)

    ```ruby
puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item|
  "I use #{item}!"
} * "\n"
```

Here’s how it looks when rendered:

puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item|
  "I use #{item}!"
} * "\n"

You can find the list of languages Pygments recognizes on the lexers page in the Pygments documentation.

WHOA!!!!! OMG!!! WOOOOOOOOOOOO AAAAAAAAAAAAA WOW OOOOOO YAAAAAAAAAAA!!!! DOUBLE RAINBOW!!!

2. Document title and footnotes

You’ll be glad to know that GitHub now shows the document title (level 0 section title) as a <h1> heading, if your AsciiDoc file has one. Previously, the document title was ignored, requiring you to use a workaround if you wanted your rendered document to start with a heading (as most people do).

What’s more, GitHub now renders footnotes where you might expect to find them, at the bottom of the document[1]. Unfortunately, the link from the reference to the footnote does not work because the HTML sanitizer wipes out the id attributes on elements (which serve as the anchors). But hey, at least you know to look for the footnote. We’ll get those links fixed in the next upgrade.

I would like to be able to tell you that include files now work, but that news will have to wait for another day once we’ve alleviated the security concerns. Until then, we at least have a solution that improves the reading experience.

If you use the include directive in your AsciiDoc, Asciidoctor replaces the directive with a link to the target file, making it easy to navigate between files from the GitHub interface. You can see an example in this sample AsciiDoc file.

4. Compliant AsciiDoc topped with syntactic sugar

The upgrade to Asciidoctor 0.1.4 brings all sorts of improvements to the AsciiDoc syntax. AsciiDoc documents are now parsed as accurately, if not more so, than if AsciiDoc Python were used. That means that AsciiDoc on GitHub is the real deal for the first time since AsciiDoc Python was put out to pasture.

Improved compliance

Here are a couple of areas of the syntax that now get parsed correctly:

  • attribute entries take effect at the location they are found in the document

    :speaker: John
:subject: Sarah

``Hi {subject}!'', shouted {speaker}.

:speaker: Sarah
:subject: John

``Hey there, {subject}!'', replied {speaker}.

  • attribute entries inside verbatim content are now properly ignored

    [literal]
:name: not an attribute entry

  • explicit substitutions can be applied to any block using the subs attribute

    [source,xml,subs="attributes,verbatim"]
--
<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>{spring-version}</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>
--

  • an alternate context may be assigned to block-level content using the first positional attribute, as permitted by the AsciiDoc syntax

    For example, an open block can masquerade as a source block, as shown here:

    [source,ruby]
--
puts 'Hello, GitHub!'
--

  • lists are parsed more accurately, especially those containing complex content

Sugar on top

On top of this compliant behavior is a sweet layer of Asciidoctor goodness. Such enhancements include:

  • shorthand id, role and options syntax for blocks

    [sidebar#audience.text-justify]
--
This content appears in a sidebar with id "audience" and justified text.
--

  • parsing of select Markdown content, including headings and quote blocks

    ## Asciidoctor speaks Markdown

> Did you here that Asciidoctor understands how to parse basic Markdown?

You bet I did!

  • implicit table header row and implicit content delimiter

    ,===
Project, Language

Asciidoctor, Ruby
AsciidoctorJ, Java
,===

  • no dropped lines for missing attributes

    Although {foobar} cannot be resolved, this line is rendered as is.

  • multiple authors in the document header, separated by semi-colons

    = Document Title
First Author; Second Author; Third Author

  • you can drop the quotes around values in block attributes if the value does not contain a comma or space

    [cols=3,width=50%]

  • custom macros, including menu, btn, kbd and icon

    :experimental:

Open a new tab by pressing kbd:[Ctrl+T] or selecting menu:File[New].

We could go on, but I’ll stop there and let you explore the many additional layers of sweetness that Asciidoctor adds.

Although the AsciiDoc syntax is correctly parsed and rendered, the output doesn’t always look as you might expect. The challenge we face is that the HTML output from Asciidoctor often relies on the stylesheet to complete the UI pattern being represented. However, those styles are not present on GitHub.

What makes things even more difficult is that the content is passed through an HTML sanitizer that strips away most of the HTML attributes, so even if we could map to existing CSS classes in the GitHub, we can’t because the class attribute gets stripped. In a future upgrade, we’ll work on finding a way to make these UI patterns work, such as admonition blocks.

5. Table of contents

Last, but not least, you can now include a table of contents in the output to help navigate those larger documents.

The first thing you need to do to enable the table of contents on GitHub is set the toc attribute in the document header.

= Document Title
:toc:

Next, you need to set the toc-placement attribute to preamble or unset the attribute.

= Document Title
:toc:
:toc-placement: preamble

If you choose preamble, the table of contents will be rendered under the preamble but before the first section. If you unset the attribute instead, you will need to place the table of contents in the document manually using the toc::[] block macro.

= Document Title
:toc:
:toc-placement!:

toc::[]

You’ll notice that superfluous bullets appear in the table of contents when rendered on GitHub. This behavior can be explained by the fact that the necessary styles are missing, as described at the end of the last section.

Long live AsciiDoc on GitHub!

The recent Asciidoctor upgrade on GitHub certainly brought with it a lot of improvements. You can see more examples showcasing what’s available in the asciidoc-samples repository.

If you already have AsciiDoc content on GitHub and you aren’t seeing the new features, you probably need to make a modification to the file to boot the rendered file from the cache and force GitHub to regenerate it.

If something still doesn’t render to your satisfaction, you have one more “escape route” option. There are three implicit attributes you can consult to conditionally include or exclude content shown in the table below. The first two are only assigned in the GitHub environment.

Attribute name Attribute value

env

github

env-github

empty string

asciidoctor-version

0.1.4

If you want to render different content when on GitHub, simply use the ifdef and ifndef preprocessor directives:

ifdef::env-github[]
I'm on GitHub!
endif::[]
ifndef::env-github[]
I'm clearly somewhere else right now.
endif::[]

If you only want to render content when the version of Asciidoctor is upgraded, then use the ifeval preprocessor directive:

ifeval::["{asciidoctor-version}" > "0.1.4"]
Asciidoctor has been upgraded again!
GitHub is now running Asciidoctor {asciidoctor-version}.
endif::[]

That wraps up our brief overview of the new AsciiDoc experience on GitHub. AsciiDoc on GitHub is no second class citizen to Markdown anymore. It’s the real deal, syntax highlighting and all.

I’d like to thank everyone who helped make this upgrade happen, including Ryan Waldron, Matthew McCullough, Tim Berglund, Garen Torikian, GitHub Security and the man who it, Brandon Keepers. Of course, I’d also like to thank everyone in the Asciidoctor community who advocates for AsciiDoc and helps make Asciidoctor awesome.

Happy documenting!

1. I’m a little footnote, short and stout.

Introducing Asciidoctor.js live preview in your browser

by Guillaume Grossetie -

I’d like to introduce you to the easiest way to render any AsciiDoc file, local or remote, as HTML directly in your browser!

All you need to do is install the Chrome extension or the Firefox add-on. Then you can preview any AsciiDoc file as HTML just by visiting it!

How it works

The Chrome extension and the Firefox add-on use Asciidoctor.js to render AsciiDoc as HTML inside your browser. Both provide a toggle button to switch between HTML output and AsciiDoc source.

Here you can see a local AsciiDoc file rendered inside of Chrome.

chrome extension enabled
Chrome extension in action
You can view any AsciiDoc file on GitHub through the lens of Asciidoctor.js with this extension! Simply navigate to the file in the GitHub web interface (try this blog post) and click the Raw button that appears above the file preview. Looks much better, doesn’t it?

Future

Currently, we are using Asciidoctor.js based on Asciidoctor 0.1.2. We planned to cross-compile the newly-released Asciidoctor 0.1.4 to Javascript, to support the latest and greatest features!

We are also working on adding some cool new features :

  • browser-based editor using MarkItUp!

  • live reload to automatically refresh on local file changes

  • and many more…​

Contributing

We’re always open for patches, better documentation, feature requests, evangelizing or any help you’re able to provide.

  • 3 of 7