# AsciidoctorJ 1.5.0 released!

#### byAlex Soto - Thursday, August 21, 2014

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

## 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!

#### byDan Allen and Sarah White - Tuesday, August 12, 2014

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.

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

• 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:

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.

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.

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
: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

### 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!

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?

### 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:

### 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!

#### byPepijn Van Eeckhoudt - Tuesday, February 18, 2014

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:

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:

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:

 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:

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!

#### byDan Allen - Tuesday, February 4, 2014

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.

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.

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::[]```

Here’s an example of how it renders:

You’ll notice that superfluous bullets appear in the table of contents. 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"]
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

#### byGuillaume Grossetie - Wednesday, September 18, 2013

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 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