Asciidoctor Maven plugin 1.5.0 released!

by Dan Allen -

Storm in Desert

The West may still be suffering from a dry spell, but we’re excited to shower Maven users with the release of version 1.5.0 of the Asciidoctor Maven plugin to Maven Central and jCenter!

This version brings all the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, plus enhancements to the site plugin. Like other versions before it, this plugin is based on the same version of the Asciidoctor and AsciidoctorJ projects (now using semantic versioning) — 1.5.0.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)

Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)

Installing or upgrading

Installing or upgrading to 1.5.0 is simple. Just update the version in your pom.xml. All necessary dependencies will be pulled in via Maven’s dependency management.

<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.0</version>
  </plugin>
</plugins>

Refer to the example project to copy-paste your way to greatness!

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

Please refer to the manual for the Asciidoctor Maven plugin for information about configuration options and other capabilities of the plugin.

Release highlights

Published the jCenter

The Asciidoctor Maven plugin is now published to Bintray’s jCenter! The means you can find the plugin more easily and its published to the future destination of binaries on the web. You can elect to get notified by Bintray when new versions are available.

Copy non-AsciiDoc files to output directory (#67)

The Asciidoctor Maven plugin now copies non-AsciiDoc files to the output directory so you can put resources, such as images or stylesheets, in the AsciiDoc source folder. This change aligns the behavior of the Asciidoctor Maven plugin with the behavior of Gradle plugin.

Add configuration for setting the gem path and loading additional gems (#109)

You can now specify the location to one or more gem installation directories (i.e., GEM_PATH) using the gemPath configuration option. The main purpose of this setting is to load additional Ruby libraries not packaged in AsciidoctorJ, such as asciidoctor-diagram. You can load additional libraries (absolute path, relative path or gem name) using the require configuration option.

Here’s an example of how to use that configuration within the plugin stanza in your pom.xml:

<configuration>
  <gemPath>${project.build.directory}/gems-provided</gemPath>
  <requires>
    <require>asciidoctor-diagram</require>
  </requires>
</configuration>
You’ll need to use the gem-maven-plugin if you want to download and install gems automatically as part of your build. Refer to the example project to copy-paste your way to greatness!
Configure AsciidoctorJ in isolation (#111)

Prior to 1.5.0, the Maven plugin would allow JRuby to see gems installed external to the project if you had the GEM_HOME or GEM_PATH environment defined (typical if you’re using RVM). This could result in non-reproducible builds.

We’ve gone part of the way of solving this problem by clearing the GEM_PATH environment variable unless it’s specified in the plugin configuration. However, the GEM_HOME environment variable won’t be cleared properly until AsciidoctorJ 1.5.1. In the interim, we issue a warning in the build if GEM_HOME is set to a path outside the build so that you know to reset the value manually (e.g., by running rvm use system).

Properly handle false and empty attribute values (#93)

There was a regression in 0.1.4 that treated both false and empty attribute values as true. Maven needs hand holding to properly convert these values. You can now use an empty string value and it will mean enable the attribute or a false value and it will mean disable the attribute. For example:

<configuration>
  <attributes>
    <toc/>
    <linkcss>false</linkcss>
  </attributes>
</configuration>

This configuration is the equivalent of the following commandline arguments to Asciidoctor:

-a toc -a linkcss!
Generate XHTML in the Maven site plugin (#61)

One of the most important improvements in Asciidoctor 1.5.0 was the addition of the XHTML backend. Simply put, this backend emits XHTML5 (XML-compliant HTML5) instead of the shorthand HTML5 that is the norm. The main reason this backend was added was to fix the behavior of the site module in the Asciidoctor Maven plugin. The XML parser that the Maven site plugin uses will thank you!

EPUB3 output

AsciidoctorJ provides integration with the Asciidoctor EPUB3 converter out of the box. That means you can use it in the Maven plugin without having to declare any additional dependencies. Just set the backend to epub3 and you’re ready to go!

The EPUB3 converter is currently alpha. Expect some glitches while the dust settles!

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

Acknowledgments

Thank you to all the contributors for helping out with this release, and for everyone involved in making Asciidoctor an awesome documentation toolchain and community! We particularly want to that the developers of the Asciidoctor Gradle plugin for giving us lots of ideas for how to make the Maven plugin great!

Enjoy building great documentation!


Asciidoctor Gradle plugin 1.5.0 released!

by Andres Almiray -

It took us longer than what we hoped but Asciidoctor Gradle plugin version 1.5.0 is finally here! The Asciidoctor Gradle plugin is based on AsciidoctorJ and, for the first time, aligns with its version numbering scheme.

Here’s the basic setup to get you started:

The plugin tracks the AsciidoctorJ version starting with this release, hence the jump from 0.7.3 to 1.5.0. There are many goodies inside Asciidoctor 1.5.0 as explained in the release notes, but perhaps the most interesting one for Gradle users is the capability to write custom extensions (or tag handlers if you will) using Groovy. You can include extensions just by placing their containing JAR in the classpath, or you can write them directly in your Gradle build, by placing the code inside buildSrc. There’s a trivial example of the latest option at github.com/aalmiray/asciidoctor-piglatin-example.

Other features found in this release are:

  • ability to load Ruby-based extensions using the requires property on AsciidoctorTask.

  • ability to set the gem installation path using the gemPath property on AsciidoctorTask.

Developers are advised to upgrade as soon as possible. Be mindful of the compatibility issues raised at the plugins’ readme. Do not forget to review the changes brought by Asciidoctor 1.5.0 found at the migration guide.

Hackergarten
Figure 1. Basel Hackergarten @ Canoo July 24th

The development team would like to thank participants of various Hackergarten sessions, both in Switzerland and abroad. Several issues and features have been contributed during those sessions. We couldn’t have done it without your help. Also, thank you to all the contributors for helping out.

Go forth and make great (and Groovy) documentation once again!

Upgrading to 1.5.0 (recommended) is simple. Just update the version in your Gradle build file. All necessary dependencies should be pulled in via Gradle.

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

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


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.

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

http://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!

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!


  • 2 of 6