Starting the AsciiDoc Specification Journey

by Sarah White and Dan Allen -

After numerous calls for an AsciiDoc specification over the past year, it’s abundantly clear the community is ready for AsciiDoc to take this step. We agree. We also reached out to Stuart, the originator of AsciiDoc, and we have his support as well. So now’s the perfect time to pursue it.

A new home at the Eclipse Foundation

We want AsciiDoc to have a strong future and the resources it needs to evolve and grow. To achieve this, we’ve decided to submit a proposal for an AsciiDoc language specification to the Eclipse Foundation. The Eclipse Foundation provides a home for developing specifications and is committed to transparency and open source, values that align well with AsciiDoc and its community. The Eclipse Foundation Specification Process (EFSP) provides a clear, yet customizable structure that reduces the risk of the process stalling and ensures the outcome will be usable in the real world. The process is public, vendor neutral, and all source materials and final artifacts are open source.

What will it mean for AsciiDoc to become a specification?

The specification for the AsciiDoc language will include an open source specification document, which defines required and optional API definitions, semantic behaviors, data formats, and protocols, as well as an open source Technology Compatibility Kit (TCK) that developers can use to develop and test compatible implementations. (Those of you who know Dan and I from before Asciidoctor know that an open source TCK is a hard requirement for us). A compatible implementation, as defined by the EFSP, must fully implement all non-optional elements of a specification version, must fulfill all the requirements of the corresponding TCK, and must not alter the specified API.

For users and developers alike, the AsciiDoc specification will mean a clear, working definition of what AsciiDoc is and how it should be interpreted. Developers will be able to build implementations, tools, and services around AsciiDoc without risk of diluting its meaning or splintering it. In turn, users will have more options, greater document portability, and the assurance that compatible implementations and tools will handle their AsciiDoc documents according to a versioned specification.

What will happen to Asciidoctor?

We plan to make Asciidoctor (the RubyGem) an independent, compatible implementation of AsciiDoc (the specification). (That doesn’t mean Asciidoctor as a whole is moving to the Eclipse Foundation). This may mean adding, removing, or changing features in Asciidoctor to meet the specification’s required and optional elements in order to pass the TCK. The Asciidoctor.js and AsciidoctorJ projects, if they choose, may also decide to become independent, compatible implementations with far greater freedom than before. And it will give space for emerging implementations to bring AsciiDoc to even more platforms.

We’ll know more—​and keep you updated on what to expect—​once the specification process gets under way.

Ready? Set. Spec!

The next step in creating the AsciiDoc specification is to propose it as a specification project to the Eclipse Foundation. The proposal, which Dan and I (as OpenDevise, on behalf of Asciidoctor) plan to submit, will be reviewed by the Eclipse Management Organization, then posted for community review and comment. To learn more about the specification process, I encourage you to check out Wayne Beaton’s posts Part II: the EFSP and Part III: Creation; you can also read the EFSP documentation.

With a specification process that can be adapted to suit the needs of the AsciiDoc community, Dan and I believe the language will evolve in a sustainable and substantive manner that keeps pace with the community’s needs, now and into the future. We’re really excited to get started, and we hope you’ll join us on this journey to make AsciiDoc a specification!


AsciidoctorJ 1.6.0 released, at last!

by Robert Panzer, Dan Allen and Sarah White -

After several years of brewing (or perhaps barrel aging?), we have finally released AsciidoctorJ 1.6.0! The artifacts are available from Bintray and Maven Central.

What is AsciidoctorJ?

AsciidoctorJ is the official library for running Asciidoctor on the JVM. With AsciidoctorJ, you can convert AsciiDoc content, analyze the structure of a parsed AsciiDoc document, and write Asciidoctor extensions in Java and other JVM languages.

Before you upgrade, there are important things you need to know, which this post covers. While AsciidoctorJ is still built on the strong foundation of the Asciidoctor RubyGem, it has matured into a project in its own right. This release brings stability and key enhancements to new and existing users alike. Grab a glass so we can pour you all the details.

A major stepping-stone to SemVer

Despite its version number, this release should be considered a major release. As such, it’s not binary compatible with the 1.5.x releases.

AsciidoctorJ 1.6.0 is a final, transitional release in preparation for the switch to Semantic Versioning (SemVer). We’re breaking the rules one last time, but for good reason. Given how long the 1.6.0 branch has been barrel aging, we wanted to allow it to be tapped to gather feedback and tease out unexpected surprises before making the jump to 2.0.0 and SemVer. If all goes well, we expect the 2.0.0 release to follow shortly after this one. At that point, we’ll begin versioning AsciidoctorJ according to the SemVer rules.

To learn more about SemVer and how it affects the Asciidoctor projects in general, see Making the Switch to Semantic Versioning.

Switching to SemVer also means that AsciidoctorJ will now be versioned independently of Asciidoctor. AsciidoctorJ has evolved into much more than just the Asciidoctor RubyGem repackaged for the JVM. It has a complete API, including Java-based extensions and tight integration with the Java ecosystem (e.g., JUL, Ruby object bridging, etc). Its own independent version line will allow it to evolve more quickly and help everyone better understand what to expect in each release. Most important, it will address the very situation that backed up the 1.6.0 release for several years.

New features

Major API and packaging changes

Since the start of AsciidoctorJ, we’ve learned so much about JRuby and how it bridges Ruby and Java objects. Using that knowledge, we’ve completely redesigned the low-level integration to address shortcomings in the original design.

That redesign required us to make breaking changes to the API, which were absolutely necessary for AsciidoctorJ to continue to move forward. But it also provided us with the opportunity to fix numerous bugs that could not be fixed in the 1.5.x line without disrupting compatibility. You’ll be happy to know that the redesign eliminates glitches that may have bitten you when writing extensions or navigating the document model using the 1.5.x releases.

As part of this change, we split the API and implementation classes into separate packages and JARs to properly isolate them. We also reconciled the competing document models by mapping all the node types in Asciidoctor and removing the ContentPart and StructuredDocument APIs. Refer to the API docs (api, impl) to see what types are available and how they are organized.

Reworked extension API

Thanks to the redesign, the JRuby-based implementation is much better hidden behind the API. In particular, there are no more references in the API to the RubyObject class from JRuby.

The interfaces for the Abstract Syntax Tree (AST) were completely renamed to better represent their purpose. For example, the AbstractNode interface was renamed to ContentNode, AbstractBlock was renamed to StructuralNode, and Inline was renamed to PhraseNode. Even more of the AST has been mapped in Java, including list and definition lists, as well as helpers for creating a table structure in an extension processor.

Overall, the APIs for extensions and the AST should feel like a pure Java library (e.g., getAttr() is now getAttribute()). You can even define extension processors using annotation-based configuration (e.g., @Name).

Check out the integrator’s guide to learn all about it and find lots of examples.

Added converter API

A new converter API has been introduced, making it possible to implement a converter for a custom output format entirely in Java. This API allows you to extend Asciidoctor from Java, similar to what you could already do using the extension APIs. You can learn how to use this new API by following the converter documentation.

In fact, there’s already one converter that’s using this API from Groovy to convert AsciiDoc to Leanpub-flavored Markdown.

Access to Asciidoctor’s logs

Asciidoctor logs error and warning messages to the Ruby logger whenever it encounters a problem in the document. When integrating Asciidoctor into your own software, it’s important to capture these log messages in order to handle them appropriately. Previously, these messages were out of reach of AsciidoctorJ. That’s no longer the case. The new Log Handling API picks up messages logged in Asciidoctor and routes them to your own log handler.

Better documentation

AsciidoctorJ 1.6.0 offers extended and tested documentation for writing extension and converters. This documentation is guaranteed to be correct because it’s tested with every commit ;) And the process is underway to incorporate the documentation into the new Antora-based documentation site for Asciidoctor.

Refer to the release notes for a more detailed account of what changed in this release. Keep in mind that, since the development of 1.6.0 ran in parallel with 1.5.x for so long, many changes from 1.6.0 may already be familiar to you as they were backported into the 1.5.x release line.

Migration notes

If you only use the Asciidoctor, Asciidoctor.Factory, and *Builder classes (e.g., Asciidoctor#convertFile), you likely don’t have to change your code. In fact, the Asciidoctor Maven Plugin and the Asciidoctor Gradle Plugin already work with this release, primarily because they only rely on the public load/convert APIs.

The necessary changes to the AST and extension APIs did introduce breaking changes that require modifying your existing extensions. Migrating an extension is a matter of conforming to the new API. This mostly involves switching to the new names for AST interfaces and aligning with the updated method signatures. Aside from the name and signature changes, the API should still be recognizable and thus compatible with your existing logic.

Here are several examples of extensions written for both AsciidoctorJ 1.5.8 and 1.6.0 to give you an idea of the types of changes to look out for:

If you have difficulty migrating your extension or document introspection code, please file an issues in the issue tracker so we can find a path forward.

Java compatibility

Asciidoctor 1.6.0 requires at least Java 8. It also runs on, and is tested against, Java 11.

Starting in AsciidoctorJ 1.6.0, the project will align its Java compatibility with the official Oracle Java SE support roadmap. While AsciidoctorJ doesn’t require Oracle Java SE, that roadmap serves as a useful signpost for which versions of Java are considered current.

Asciidoctor 1.6.0 does not yet support running on the module path, a key feature of the Java Platform Module System introduced in Java 9. We’d like to get there in an upcoming version. That will depend, however, on the progress AsciidoctorJ’s dependencies make towards this goal, most notably JRuby. Despite this limitation, you can still run Asciidoctor 1.6.0 on Java 11.

Acknowledgements

We’d like to take this opportunity to name several key individuals who came together to make this release what it is today.

  • Jérémie Bresson for initiating the split between the API and implementation packages and modernizing the API signatures.

  • Abel Romero for his help with the design of the JUL logging integration and for testing it in the Maven plugin first.

  • Frank Becker for overhauling and streamlining the Gradle build.

  • Guillaume Grossetie for loads of cleanups and improvements across the API and implementation and for stress testing the redesign by launching AsciidoctorG.

  • Charles Nutter, Thomas Enebo, and the JRuby team for creating and maintaining JRuby, on which AsciidoctorJ is based.

  • And finally, our “elder”, Alex Soto for starting the AsciidoctorJ project and showing us a vision of what’s possible.

Of course, there are many more people to thank. As we’ve said many times, this project would not be possible without the incredible work and collaboration by the many volunteers who work on it. So, thank you!

Outlook for 2.0.0

The breaking changes aren’t over just yet. Heading towards 2.0.0, we want to further split the API of AsciidoctorJ and its implementation. Our big goal is to support alternative implementations underneath, such as Asciidoctor.js, using the same public API.

To help us get to 2.0.0, we ask that you test 1.6.0 and let us know if you run into any problems or changes that prevent you from migrating to it. Now’s the chance to get it right before the 2.0.0 release. Please file any issues you find in the issue tracker.

Thank you for coming on this journey with us as we work to bring the very best of AsciiDoc to the JVM.


Making the switch to Semantic Versioning

by Dan Allen -

After years of talking about it, we’re finally ready to make the switch to Semantic Versioning in Asciidoctor. This switch will happen as part of the next major release for each participating project.

About Semantic Versioning

Semantic Versioning (or SemVer, for short) is a logical system for selecting version numbers based on a simple MAJOR.MINOR.PATCH sequence.

  • A MAJOR version is for introducing incompatible changes (large or small).

  • A MINOR version is for adding backward-compatible functionality.

  • A PATCH version is for making bug fixes (backward compatible, of course).

There’s also room for a prerelease version via build metadata. You can learn more at https://semver.org.

In our current system, patch releases are indistinguishable from major and minor releases and there’s only a single release line. Experience has taught us (the hard way) that this situation is neither clear or sustainable. For us, SemVer is about having better communication and room to grow. It’s a system based on shared expectations and trust. Although it may not be perfect, SemVer should help to understand what a version number entails and when to upgrade. We can’t expect it to prevent breaking something, but at least you’ll know when it might.

Versioning projects independently

Switching to SemVer also means that the Asciidoctor projects, namely Asciidoctor, AsciidoctorJ, and Asciidoctor.js, will be versioned independently. Other projects in the ecosystem will likely start versioning independently as well (in fact, some already have).

AsciidoctorJ and Asciidoctor.js have both reached a point where the projects are much more than a redistribution of the Asciidoctor RubyGem. They have their own API, extensions model, custom features, and platform integration. And that warrants having their own version line. An independent version line will also allow users to better understand what to expect in each release.

After speaking with Robert (AsciidoctorJ lead) and Guillaume (Asciidoctor.js lead), here’s the system we agreed on:

  • The core processors (Asciidoctor, AsciidoctorJ, and Asciidoctor.js) will move to SemVer starting with the 2.0.0 release. We plan for all three projects to make this major version shift at roughly the same time to minimize confusion.

  • If Asciidoctor.js or AsciidoctorJ need a change in Asciidoctor, they can force Asciidoctor to be released. This means Asciidoctor will need to be “release ready” at all times. A patch or minor release won’t need much discussion, but a major release will, of course.

  • We will not attempt to align the version numbers between the three projects after 2.0.0. Guillaume laid out a strong case that trying to align the version numbers would work against SemVer and thus result in the version numbers losing their meaning. This does introduce the complexity of having to document the version of Asciidoctor that Asciidoctor.js or AsciidoctorJ provides. However, both AsciidoctorJ and Asciidoctor.js provide an API for accessing the version of the underlying Asciidoctor release. The release number is also available via the asciidoctor-version document attribute.

We considered ways to lock Asciidoctor, AsciidoctorJ, and Asciidoctor.js to the same version while still adhering to SemVer. However, we reached the conclusion that doing that would only perpetuate the situation that’s caused the backup of releases we’ve seen. It’s best if the projects have the freedom to release when the time is right to release. And with three version number segments (MAJOR.MINOR.PATCH), we finally have enough space for those releases to happen!

Next steps

We’ll start by repackaging the Asciidoctor 1.5.8 release as 2.0.0, with some minor adjustments to drop unsupported versions of Ruby. AsciidoctorJ and Asciidoctor.js will then follow with their 2.0.0 releases. At that point, we’ll stick to versioning according to SemVer rules as outlined above.


Les outils pour débuter avec Asciidoctor

by Guillaume Scheibel and Maxime Gréau -

Vous venez de découvrir Asciidoctor et vous vous demandez par où commencer pour être rapidement efficace avec vos documents AsciiDoc ? Voici ci-dessous la liste des possibilités pour genérer et visualiser le code HTML associé au contenu AsciiDoc.

DocGist : éditeur en ligne

DocGist est un éditeur en ligne pour AsciiDoc qui vous permet notamment d’éditer des documents en proposant le rendu HTML en temps réel, de partager vos documents avec d’autres utilisateurs, et de travailler à plusieurs sur un même document. Cet outil ne nécessite aucune installation spécifique, ni de création de compte.

Il est disponible à l’adresse http://gist.asciidoctor.org

DocGist

Les extensions pour navigateurs

Il est possible de visualiser, en temps réel, le rendu HTML de fichiers sources AsciiDoc locaux ou distants grâce à de simples extensions pour navigateurs.

Extension Chrome

L’extension Asciidoctor.js Live Preview pour Chrome vous permet également de sélectionner des thèmes prédéfinis ou d’importer votre propre thème personnalisé (CSS).

Plus d’informations sur le projet GitHub asciidoctor-chrome-extension.

Chrome Asciidoctor.js Live Preview

Addon Firefox

L’addon Asciidoctor.js Live Preview pour Firefox propose comme les autres extensions la visualisation HTML en temps réel.

Pour utiliser la version la plus à jour de l’addon, il est préférable de l’installer en téléchargeant la dernière release à partir de GitHub.

Plus d’informations sur le projet GitHub asciidoctor-firefox-addon.

Firefox Asciidoctor.js Live Preview

Addon Opera

Les extensions Chrome étant compatibles avec Opera, cet addon est le même que pour Chrome, il offre donc des fonctionnalités identiques.

Plus d’informations sur le projet GitHub asciidoctor-chrome-extension. (Oui, cet addon est le même que pour Chrome).

Opera Asciidoctor.js Live Preview

Les éditeurs de texte modernes

Asciidoctor est présent dans la plupart des éditeurs de texte modernes, un éditeur dédié lui est également consacré.

AsciidocFX

AsciidocFX est un éditeur basé sur Asciidoctor qui propose un nombre très important de fonctionnalités : multi-plateforme (Windows, Mac, Linux), export en PDF, HTML, MOBI, EPUB et plus.

La documentation complète du projet est disponible sur le site http://asciidocfx.com/.

AsciidocFX Editeur

Packages pour Atom

La communauté Asciidoctor propose 2 packages complémentaires pour Atom:

AsciiDoc Preview package

Ce package active la visualisation en temps réel du HTML correspondant au AsciiDoc saisie. Il propose également de l’auto-complétion pour les variables d’Asciidoctor.

AsciiDoc package

Ce package active le support du langage AsciiDoc avec notamment la coloration syntaxique.

Atom Editeur

Extension pour Brackets

L’extension AsciiDoc Preview pour l’éditeur Brackets de Adobe propose, en outre de la visualisation HTML en temps réel, des fonctionnalités intéressantes comme la possibiité de synchroniser la position courante dans le source AsciiDoc avec la section HTML correspondante. Cette extension supporte les expressions mathématiques ainsi que les diagrammes PlantUml, Ditaa et Graphviz.

Plus d’informations :

asciidoctor bracket extension demo

IntelliJ

Pour les dévelopeurs Java, le plugin IntelliJ (IDEA et la famille) pour AsciiDoc permet de rester dans le même environnement pour écrire du code et la documentation associée.

Plus d’informations sur le projet GitHub asciidoctor-intellij-plugin.

asciidoctor intellij plugin demo

Installer Asciidoctor

A partir des gems

$ gem install asciidoctor
$ gem install asciidoctor-diagram
$ gem install asciidoctor-pdf --pre
$ gem install asciidoctor-epub3 --pre

Retrouvez toutes les gems (officielles ou non) sur RubyGem.

A partir d’un container

$ docker pull asciidoctor/docker-asciidoctor (1)
$ docker run -v $(pwd)):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D /documents *.adoc (2)
1 Téléchargement à partir du DockerHub de l’image Docker Asciidoctor officielle en local.
2 Exemple d’utilisation d’Asciidoctor dans un container.

Plus d’informations sur le projet GitHub docker-asciidoctor.

Les environnements de build

Afin de générer la documentation à partir d’un système d’Intégration Continue, par exemple, Asciidoctor propose des plugins pour les outils de constructions en environnement Java.

Plugin Maven

pom.xml
<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.3</version> (1)
        ...
    </plugin>
</plugins>
1 La version du plugin est proche de la gem Ruby principale.

Plus d’informations sur la configuration Maven avec le projet asciidoctor-maven-plugin.

Des exemples de configuration selon les cas d’utilisations sont disponibles dans le projet asciidoctor-maven-examples.

Plugin Gradle

build.gradle
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
    }
}

apply plugin: 'org.asciidoctor.convert'

Plus d’informations sur la configuration Gradle avec le projet asciidoctor-gradle-plugin.

Des exemples de configuration selon les cas d’utilisations sont disponibles dans le projet asciidoctor-gradle-examples.

Tâche Ant

build.xml
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
    <target name="doc">
        <taskdef uri="antlib:org.asciidoctor.ant" resource="org/asciidoctor/ant/antlib.xml" classpath="lib/asciidoctor-ant.jar"/> (1)
        <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
    </target>
...
</project>
1 “lib” est le répertoire qui contient le JAR asciidoctor-ant.jar.

Plus d’informations sur la configuration Ant avec le projet asciidoctor-ant.


Funding for Asciidoctor

by Dan Allen and Sarah White -

With Asciidoctor, we’re working to shape the future of writing and publishing, particularly in the field of technical documentation. We want people to use open source not only because it’s the best software, but because it’s the best documented software.

We’ve come a long way. We have even bigger plans for the future. To turn our vision into reality, the Asciidoctor project needs funding.

Bountysource

In order to ensure the continued success and sustainability of the Asciidoctor project, we’ve setup an account for Asciidoctor on Salt, the new funding platform from Bountysource. (Bountysource is like Kickstarter for open source projects). You can read more details about this campaign, how it works and our initial goals on the Asciidoctor campaign page.

The Salt platform will enable us to accept financial backing for Asciidoctor from both organizations and individuals and allocate the money the way we think best suits the project. It will also allow us to be completely transparent about how the project is funded. The initial goal is to allow us (Dan and Sarah) to work on Asciidoctor full time.

Asciidoctor growth

Asciidoctor has grown and matured substantially over the last three years. It’s now a critical component of documentation, especially in open source. In order to keep up with the project’s rate of growth, manage the Asciidoctor ecosystem as a whole, and be there to facilitate participation, we need to be able to dedicate more time and attention to this work. We also need to cover current and future infrastructure costs. The more money this campaign raises (on an ongoing basis), the more we can achieve, the more possibilities we can unlock and the greater the impact Asciidoctor can have.

By securing funding, the Asciidoctor project can essentially hire us (Dan and Sarah) to keep it operating smoothly and releasing components more frequently. We love running the Asciidoctor project and we love the community. We want to continue serving the community and doing what we love to make a toolchain writers have always wanted.

Let’s make it happen!

If you have questions or concerns, please don’t hesitate to respond.


  • 1 of 7