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.

Use Arquillian and Docker to verify that AsciidoctorJ works in WildFly

by Maxime Gréau -

We’re excited to announce the newest member of the Asciidoctor family, Docker AsciidoctorJ. The Docker AsciidoctorJ project ensures that AsciidoctorJ can be used by any application deployed to a Java EE application server*.

* For now, only WildFly is tested. Pull requests welcome!

What’s it about?

This project provides:

A Dockerfile

Builds a Docker image that includes WildFly 8.2, AsciidoctorJ 1.5.2 and AsciidoctorJ PDF 1.5.0

Arquillian tests

Uses AsciidoctorJ inside a Docker container to convert AsciiDoc files to HTML and PDF files

AsciidoctorJ WildFly Docker containers managed by Arquillian
Figure 1. The power of Arquillian & Docker for integration testing AsciidoctorJ in WildFly

Learn more!

The following post explains how we execute Arquillian tests for AsciidoctorJ in a WildFly Docker container. We’ll talk about:

Want to know more? Read the full blog post to get all the details.

Asciidoclet 1.5.0 released!

by John Ericksen and Ben Evans -

Following on from the releases of Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, version 1.5.0 of Asciidoclet has been released with several significant new features, including a new look & feel!

What is Asciidoclet?

Asciidoclet allows Java developers to write Javadoc comments in the portable and rich AsciiDoc syntax instead of HTML.

In short, why write messy Javadoc like this?

/**
 * This class has the following features:
 * <ul>
 *   <li>Support for <strong>foo</strong></li>
 *   <li>Support for bar</li>
 * </ul>
 */
public class Thing implements Something { ... }

…​when you can write tidy Javadoc like this!

/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

Much better! Now comments in the source code are much easier to read and write and can be reused outside of Javadoc. Best of all, the HTML generated from Javadoc still looks great (perhaps even better).

Of course, this example just scratches the surface of what’s possible. Tables, lists, code examples with syntax highlighting, links, includes and all of Asciidoctor’s capabilities are available via the lightweight AsciiDoc syntax.

Now, developers can focus on content rather than formatting, and still achieve a beautiful end result.

Artifact information

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

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)
Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)

Installing

In Maven, just add the Asciidoclet doclet name and artifact to the maven-javadoc-plugin declaration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <doclet>org.asciidoctor.Asciidoclet</doclet>
    <docletArtifact>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoclet</artifactId>
      <version>1.5.0</version>
    </docletArtifact>
  </configuration>
</plugin>

See the Asciidoclet guide for examples that apply to other build systems and all the available doclet options.

Release highlights

Built on Asciidoctor 1.5.0

Asciidoclet inherits all of the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0.

Asciidoctor 1.5.0 introduced some syntax changes. Please refer to the migration guide for details about how to migrate your content.

Improved stylesheets

Asciidoclet includes a default stylesheet with styles from Asciidoctor 1.5.0. This means that AsciiDoc content in the Javadoc is rendered with a similar look and feel to Asciidoctor in other environments.

Javadoc output
Figure 1. Example Javadoc using the Java 8-derived stylesheet

Javadoc’s HTML output varies between releases of the Java platform, so Asciidoclet selects an appropriate stylesheet based on the Java version it is running under:

  • For Java 7 & 8, a stylesheet based on the default Java 8 Javadoc stylesheet is used.

  • For Java 5 & 6, the stylesheet is based on the Java 6 Javadoc stylesheet.

If you want to use your own stylesheet, you can still do this by using Javadoc’s -stylesheetfile option.

AsciiDoc overview files

Javadoc’s -overview option lets you specify an HTML file that will be used as the overview or index page in the generated documentation. This is especially useful for larger projects, where the overview can provide users with a useful introduction and help them to navigate the API.

Asciidoclet now supports overview files written in AsciiDoc as well, with full support for AsciiDoc features such as includes and document attributes. Overview files named *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML, and will be processed by Javadoc’s standard doclet.

Document attributes

Asciidoclet now fully supports Asciidoctor’s document attributes. These are one of Asciidoctor’s most powerful features. Document attributes are parameters that can be passed to Asciidoctor to affect how the final output is generated.

Attributes are specified using one or more -a (or --attribute) options when running Asciidoclet. The --attributes-file option reads attributes from an AsciiDoc file. The attributes are passed to Asciidoctor when it renders Javadoc comments.

Here are some examples of how document attributes might be useful in your Javadoc.

Variable substitution

Attribute references in Javadoc comments or overview files are replaced with attribute values:

/**
 * {product-name} will change your life!
 * @version {version}
 */

When the doclet is run with -a product-name=Foo -a version=1.0, Asciidoctor replaces all {product-name} and {version} attribute references with the given values in the generated HTML output. This makes it very simple to inject values into the Javadoc, without changing the source.

Conditional inclusion

AsciiDoc’s conditional directives can selectively include content based on the presence or absence of attributes. This is useful when the same AsciiDoc source is used in different environments.

For example, if you wanted to reuse the same AsciiDoc content in your Javadoc overview page and your web site, but with some differences, you can use attributes to tell Asciidoctor when certain content should be included:

= Documentation for the Foo project

ifdef::javadoc[]
// content that should only appear in Javadoc
endif::javadoc[]

ifdef::my-website[]
// content that should only appear on the web site
endif::my-website[]

Asciidoclet automatically sets the javadoc attribute when it runs, so Javadoc-only content can easily be selected. You can of course define your own attributes as well.

Java and Ruby extension support

Asciidoctor can be extended using Java or Ruby libraries, and Asciidoclet inherits this capability as well.

  • Java extensions are loaded automatically when they are made available in the classpath, using AsciidoctorJ’s Extension SPI.

  • Ruby libraries (Gems) are loaded using the -r (or --require) option.

When using the --require option, we recommend specifying the --gem-path option as well to explicitly set the location of installed gems. Doing so ensures that your build remains portable and reproducible. You can use the gem-maven-plugin to install gems directly into your build directory.

Many extensions are available, but one that is probably most useful for Javadoc authors is Asciidoctor Diagram. Let’s see how it can be used with Asciidoclet.

Embedding diagrams in Javadoc

Asciidoctor Diagram is a popular Asciidoctor extension that lets you embed plain text diagram descriptions in your AsciiDoc source, which get rendered to images when Asciidoctor runs. This can be extremely valuable in Javadoc for describing the architecture or behavior implemeted by the software.

Here’s an example of a Javadoc comment containing a PlantUML sequence diagram:

/**
 * This class implements the following protocol:
 *
 * [plantuml]
 * ....
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 *
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * ....
 */
public class AuthServer { ... }

Here’s how the diagram above appears in the Javadoc output:

Example output using Asciidoctor Diagram
Figure 2. Example output using Asciidoctor Diagram

Not bad! Developers can easily view and update diagrams in plain text, and users reading the Javadoc will see nicely rendered images.

Many other types of diagrams are supported, including Graphviz, blockdiag and ditaa. See the documentation for Asciidoctor Diagram for more examples.

To enable Asciidoctor Diagram support in Asciidoclet:

  1. Install the Asciidoctor Diagram gem, asciidoctor-diagram:

    $ gem install asciidoctor-diagram

  2. Run Asciidoclet with the following doclet options:

    --require asciidoctor-diagram
--gem-path ${env.GEM_PATH} (1)
--attribute data-uri (2)
    1 The --gem-path ${env.GEM_PATH} option tells Asciidoctor’s JRuby runtime where to find gems when using --require (effectively setting the $GEM_PATH environment variable internally).
    2 The data-uri attribute is required so that the image data is embedded inside the generated HTML files.[1]

  3. Admire the beautiful diagrams adorning your Javadoc!

Thanks!

We hope this new version makes your Javadocs even better. We appreciate everyone who has contributed to Asciidoclet. If you have ideas about how to improve on it, ideas and pull requests are always welcome via the repository on GitHub.

1. Without the data-uri attribute, Asciidoctor Diagram writes image files to a location that doesn’t line up with the generated HTML. This problem is being addressed in Asciidoctor Diagram at the time of writing. Refer to issue #39 for details.

Asciidoctor.js 1.5.0 released to Bower and npm!

by Guillaume Grossetie and Anthonny Quérouil -

The release train is on the move! Version 1.5.0 of Asciidoctor.js has been released and is now available in Bower and npm. This release is an important step toward making Asciidoctor.js widely available to the JavaScript ecosystem.

Bower and npm 
Asciidoctor in JavaScript.
It was a dream.
Then it was a prototype.
Now, it’s the real deal.
What is Asciidoctor.js?

Asciidoctor.js is the official library for using Asciidoctor in JavaScript. It shares the same source code as Asciidoctor and is transcompiled to JavaScript using Opal. With Asciidoctor.js, you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from JavaScript.

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

Release highlights

Asciidoctor.js is Asciidoctor

As mentioned in the release notes for Asciidoctor 1.5.0, we worked hard to align Asciidoctor.js (JavaScript) and Asciidoctor core (Ruby). That means you can expect Asciidoctor.js to parse and convert documents just like the original. Even includes work!

Getting certain features to work, like includes, requires special consideration because JavaScript is a different environment than Ruby and there are even key variations between JavaScript environments!

For example, reading an include file in Ruby is just a matter of using the normal Ruby IO API. In a browser environment, we have to use XMLHttpRequest (i.e., Ajax) as the IO API instead. If Asciidoctor.js is running on Node.js, we have to use the Node IO API, fs.readSync(), to make it work.

Rest assured we’re continuing to work on smoothing any differences to bring all the great features of Asciidoctor core to JavaScript.

Read on to learn how to get your hands on Asciidoctor.js!

Using Asciidoctor.js is easier than ever before

If you are a frontend or backend JavaScript developer, you’re only one command away from getting the latest version of Asciidoctor.js

Bower package

Installing Asciidoctor.js with Bower
$ bower install asciidoctor.js --save
The optional --save flag automatically adds the package to your project’s dependencies.

Once the package installed, you can add the following script tag to your HTML page:

<script src="bower_components/asciidoctor.js/dist/asciidoctor-all.min.js"></script>

The asciidoctor-all.min.js is a minified version and includes Asciidoctor core, extensions API and Opal.

Here is a simple example that converts AsciiDoc to HTML5 using the doctype: 'inline' option and showtitle attribute:

var asciidoc = "http://asciidoctor.org[*Asciidoctor*] " +
    "running on http://opalrb.org[_Opal_] " +
    "brings AsciiDoc to the browser!";
var options = Opal.hash2(['doctype', 'attributes'], {doctype: 'inline', attributes: ['showtitle']});
var html = Opal.Asciidoctor.$convert(asciidoc, options);
console.log(html);

See the Front-end development guide to learn more about the Bower package.

npm package

Installing Asciidoctor.js with npm
$ npm install asciidoctor.js --save
The optional --save flag automatically adds the package to your project’s dependencies.

Once the package is installed, the first thing to do is to load the asciidoctor.js module using require, then you’re ready to start using the API:

sample.js
var asciidoctor = require('asciidoctor.js')(); (1)
var opal = asciidoctor.Opal; (2)

var processor = null;
var useExtensions = true;

if (useExtensions) {
  processor = asciidoctor.Asciidoctor(true); (3)
}
else {
  processor = asciidoctor.Asciidoctor(); (4)
}

var content = "http://asciidoctor.org[*Asciidoctor*] " +
    "running on http://opalrb.org[_Opal_] " +
    "brings AsciiDoc to Node.js!";
var options = opal.hash2(
    ['doctype', 'attributes'],
    {doctype: 'inline', attributes: ['showtitle']});
var html = processor.$convert(content, options); (5)
console.log(html); (6)
1 Load the Asciidoctor.js library
2 Retrieve and alias the top-level Opal namespace
3 Instantiate Asciidoctor with extensions enabled
4 Instantiate Asciidoctor without extensions
5 Convert AsciiDoc content to HTML5 using Asciidoctor.js
6 Print the HTML5 output to the console

Save the file as sample.js and run it using the node command:

$ node sample.js

You should see the following output in your terminal:

<a href="http://asciidoctor.org"><strong>Asciidoctor</strong></a> running on <a href="http://opalrb.org"><em>Opal</em></a> brings AsciiDoc to Node.js!</p>
To be successful with Asciidoctor.js, it’s important to understand how to work with Ruby objects in the JavaScript environment. We recommend that you browse the Opal documentation to learn how method names are mapped and what data types it expects.

See the Back-end development guide to learn more about the npm package.

Asciidoctor.js is heating up on Node

Node.js is where the hottest JavaScript is happening and npm is the package manager that manages and distributes that hotness. We wanted Asciidoctor.js to be a part of this ecosystem. We also needed it there to start building tools. That’s why we took the first step of packaging Asciidoctor.js as an npm package…​in fact, several! Asciidoctor now has a new playground!

Here are the npm packages that are published:

asciidoctor.js

the main npm package for Asciidoctor.js

grunt-asciidoctor

an npm package for processing AsciiDoc source files in your Grunt project

Here’s how the community is playing with these packages already:

asciidoc-preview (Atom Editor)

A plugin for Atom that shows you a preview of your document while you type!

asciidoc-preview (Brackets Editor)

An extension for Brackets that shows you a preview of your document while you type!

grunt-asciidoctor-assemble

a static website generator for Grunt by @tedbergeron

Of course there are still challenges, but we’ll solve them. Head over to the Asciidoctor.js project to get involved.

Let us play this new game!

Asciidoctor.js on the JVM

You read that right. The browser ain’t the only JavaScript game in town. (And we’re not talking about JavaScript engines that have escaped from the browser, like Node.js.) We’re talking about the most polyglot of polyglot runtimes, the JVM.

Alex Soto is working at getting Asciidoctor.js integrated into AsciidoctorJ so you can use it on the JVM using Nashorn, dynjs and other JavaScript engines that run on it. The AsciidocFX project is already using Asciidoctor.js on Nashorn, so it’s more than just an idea!

There are still several challenges to tackle to ensure Asciidoctor.js runs smoothly on the JVM, such as getting includes working. Head over to the AsciidoctorJ project to get involved and help make it happen!

Acknowledgments

The alignment of Asciidoctor.js with Asciidoctor core was a major effort. It required input from a lot of people and they really pulled together to meet this challenge.

We want to especially thank the Opal developers, notably Adam Beynon, meh and Elia Schito, for making Asciidoctor.js happen. They were very responsive to our effort, making changes and fixes to Opal and generally providing input that allowed us to continuously move forward.

We also want to thank Anthonny Quérouil for crafting a Grunt build to compile, aggregate and compress Asciidoctor.js and for helping to get the artifacts published to Bower and npm.

Thanks to everyone who tested Asciidoctor.js, either directly or by using the tools. Your participation has helped Asciidoctor.js become the real deal!

If you have questions or feedback, we encourage you to participate in the discussion list. Talk to you there!

  • 1 of 6