A new resource for AsciiDoc

by Dan Allen -

AsciiDoc is an excellent tool for writing documentation, but there’s simply not enough information about it.

Today, I’m excited to announce a new resource for AsciiDoc, asciidoctor.org. In addition to serving as the project page for the Asciidoctor project and its integrations, this website helps promote AsciiDoc through education and advocacy.

dawn
The dawn of a new era Photo credit: bartvandorp

The key highlight of the site is a collection of new AsciiDoc guides:

The purpose of these guides is to answer your questions about AsciiDoc and get you familiar with the syntax quickly. They present AsciiDoc by following a recommended set of conventions to help you create more consistent documents and maximize your writing productivity.

If you see a change you want to make, contributing to the guides is easy!

The guides are written in AsciiDoc and hosted on GitHub. If you see a change you want to make in one of the guides, just look for the Edit button in the right-hand column and click on it. That will take you to an editor on GitHub where you can make the change and submit it as a pull request.

Alternatively, you can clone the project, make the change locally, commit it, then send a pull request in the usual way.

Once the change is merged into the master branch, it gets published automatically.

I hope you find the guides useful, and I look forward to your feedback. Together, we can take the agony out of writing documentation!

AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories

by Dan Allen -

Since early December and throughout the holidays, GitHub’s Ryan Waldron, Red Hat’s Dan Allen and other contributors have collaborated on Asciidoctor (project site, code repository), a new open source implementation of AsciiDoc written purely in Ruby[1].

The implementation kicked off with two core goals in mind:

  1. Improve the rendering of AsciiDoc source files in git repositories and gists on GitHub

  2. Bring AsciiDoc to the Ruby world by offering the first compliant Ruby port of the markup language

After a lot of hard work and a thorough security audit, we’re thrilled to announce that…​

Note Asciidoctor is now deployed to render AsciiDoc markup in any of the 5 million+ repositories on GitHub.

Asciidoctor 0.1.0 is also available on rubygems.org and can be installed locally via RubyGems (gem install asciidoctor).

About AsciiDoc

AsciiDoc is a lightweight markup language akin to Markdown. Going beyond Markdown, AsciiDoc supports all the structural elements necessary for drafting articles, technical manuals and books. Several O’Reilly authors, including Matthew McCullough, Tim Berglund and Matt Neuburg, have used it to write books for that iconic technical library. AsciiDoc is fully capable of serving as a shorthand replacement for DocBook, which it can also output.

DocBook is nice, but (like XML) it is not meant for editing nor for merging changes (by humans). Using AsciiDoc (which translates to DocBook perfectly) is a much easier way of developing.

— Dag Wieers

One way to think of the relationship between AsciiDoc and DocBook is that AsciiDoc is to DocBook as RelaxNG Compact is to XML Schema. With AsciiDoc, you drop the angled-brackets (i.e., XML), but not the semantics.

Here’s an example of a document written in AsciiDoc, shown above the output it produces:

(You don’t want to see how the DocBook looks for this example. Let’s just say, there isn’t enough room on the screen to show it to you.)

Source document

 
= Asciidoctor
Ryan Waldron, Dan Allen

http://asciidoctor.org[Asciidoctor] is a native Ruby processor
for converting AsciiDoc source files and strings into HTML 5,
DocBook 4.5 and other formats.

== Installation

You can install the Asciidoctor RubyGem using the +gem+ command:

 gem install asciidoctor

On Fedora, you can install via an RPM package
(https://bugzilla.redhat.com/show_bug.cgi?id=889011[pending])
using the +yum+ command:

 yum install rubygem-asciidoctor

Now you are ready to start using Asciidoctor!

== Benefits

Asciidoctor is:

* compliant
* fast
* secure
* stable

'Give it a try!'

Rendered HTML Output

Asciidoctor

Ryan Waldron, Dan Allen

Asciidoctor is a native Ruby processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats.

Installation

You can install the Asciidoctor RubyGem using the gem command:

gem install asciidoctor

On Fedora, you can install via an RPM package (pending) using the yum command:

yum install rubygem-asciidoctor

Now you are ready to start using Asciidoctor!

Benefits

Asciidoctor is:

  • compliant

  • fast

  • secure

  • stable

Give it a try!

The AsciiDoc project, written in Python, was the only implementation of the AsciiDoc syntax…​until the arrival of "the doctor".

The Asciidoctor implementation

Asciidoctor is the first project to implement the AsciiDoc syntax in another language, in this case Ruby. It’s an open source library (MIT licensed) published as a RubyGem to rubygems.org. The project recently moved to the Asciidoctor organization on GitHub to sustain its rapid growth.

While Asciidoctor aims to offer full compliance with the AsciiDoc syntax (with some exceptions, noted in the project README), it’s more than just a clone.

Built-in and custom templates

Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook 4.5 output that is structurally equivalent to what AsciiDoc produces. Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. Custom template rendering is handled by the Tilt template abstraction library, a project created by another GitHubber, Ryan Tomayko.

Parser and object model

Leveraging the Ruby stack isn’t the only benefit of Asciidoctor. Unlike the AsciiDoc Python implementation, Asciidoctor parses and renders the source document in discrete steps. This makes rendering the document optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. Developers can use the full power of the Ruby programming language to play with the content in the document.

Performance and security

No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. It loads, parses and renders documents at least 25 times as fast as the Python implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.

Beyond Ruby

Asciidoctor’s usage is not limited to the Ruby community. Thanks to JRuby, a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well (and eventually in Java build tools like Apache Maven). Asciidoctor also ships with a command-line interface (cli), written by Red Hat’s Jason Porter. The Asciidoctor cli, asciidoctor, is a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.

The future of Asciidoctor and AsciiDoc

The future is bright for AsciiDoc. Despite being a seasoned, 10-year-old markup language, adoption of AsciiDoc has never been stronger. The developers have lots of ideas about how to improve and extend Asciidoctor, some of which push beyond the AsciiDoc syntax.

  • If you’re interested in using AsciiDoc, head over to GitHub and create a new file in one of your repositories or gists using the file extension .asciidoc or .adoc.

  • If you’re interested in contributing to Asciidoctor, in turn helping to move AsciiDoc forward, your participation and feedback is welcome!

Write docs with pleasure!

This article was composed in AsciiDoc and rendered using Asciidoctor.
1. The Asciidoctor code base emerged from a prototype that GitHub developers created last year to produce the git man pages shown on the git website.

Wow! AsciiDoc is incredible!! I’m impressed! (2012)

by Dan Allen -

As you may have heard, Google+ is sinking into the sea. Sadly, it’s going to take with it the post I made when I first discovered AsciiDoc…​where it all began. My interest in AsciiDoc, and even the origin of Asciidoctor, can be traced back to this post. So we don’t lose this bit of history, I’ve decided to preserve it here on the Asciidoctor blog. Keep in mind that some of the references in this post are outdated.

The Google+ Post

I now consider myself well-versed in AsciiDoc after spending two days converting several full-length technical tutorials to AsciiDoc and really digging deep into its capabilities.

AsciiDoc is a lightweight, yet powerful markup language that’s got it all:

  • It’s readable

  • It’s comprehensive

  • It’s extensible

  • It produces beautiful output (in HTML, DocBook, PDF, ePub and more)

Now this is a lightweight markup language worthy of producing a book!

If you are interested in using it to write a book, see git-scribe: https://github.com/schacon/git-scribe

Think of it this way:

If Markdown is a 1st-grader, then AsciiDoc is PhD student.

For basic formatting, Markdown and AsciiDoc look remarkably similar, making AsciiDoc a drop-in, no-brainer replacement to Markdown (both in terms of simplicity and straightforward migration). Yet, the AsciiDoc syntax seems to continue on with no end. In fact, there is no end since it can be extended (and tweaked) rather easily.

What about Docbook? Ah! The great thing about AsciiDoc is that you can still produce Docbook without any of the pain or without sacrificing any features. Perhaps AsciiDoc should adopt this slogan:

Writing in Docbook is just, inhumane.

I could list all features AsciiDoc supports, but a showcase speaks for itself: http://powerman.name/doc/asciidoc

Getting back to my experiment…​

I had the opportunity to seriously evaluate and contrast the serious lightweight markup languages: reStructuredText (and its complement Sphinx), Textile and AsciiDoc. Hands down, AsciiDoc is the winner. If there’s such a thing as a sure thing in software, AsciiDoc is it.

I first converted a full-length technical tutorial into reStructuredText. It took roughly 3 hours to struggle through the syntax and get it converted, with holes still remaining here and there. The syntax is just quirky (what’s the obsession with backticks and colons?) and hard to commit to memory. On the whole, it just leaves a bad taste. I was pretty deflated and ready to throw in the towel.

On my way to bed, a hint of curiosity motivated me to give AsciiDoc a shot. Within 15 minutes I had converted the whole document. Plus, I had outputs in HTML, PDF, plain text, ePub and Docbook to show for it. I was even starting to play with additional formatting and organization features. I felt like I found the holy grail of documentation.

Here’s the result of that experiment:

Source

http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc

Conf

http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.conf

HTML

http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html

PDF

http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.pdf

Documentation can be easy and fun. Who would have thought?

I’m about as excited about AsciiDoc as I am about git (and the combination is just bliss). And there’s still so much to explore. I definitely encourage you to check it out. AsciiDoc is even supported as a markup format on github (and gists), making it easy to get started.

If you’re on Fedora, download the latest version of AsciiDoc from the website rather than install the RPM. The RPM is missing files from the distribution.
Update (2014-08-15)
Since this post is often referenced for information about AsciiDoc, I’m updating it to point to a more recent AsciiDoc cheatsheet. See http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/.

Post Activity

Comments

39
+1s

57
Shares

24
Participants

Henry Lee +1’d, Milan Navrátil +1’d, Ravishankar Haranath +1’d, Markus C +1’d, Chris Drew +1’d, csgeek reshared, Andrey “Bass” Shcheglov +1’d, Gavin Engel +1’d, Марк Сафронов +1’d and reshared, Liam OBrien +1’d, Anatoly Yakubov +1’d, Mhd Shulhan +1’d, Kartik Singhal +1’d, Ahmad Khayyat +1’d, Benjamin Kampmann reshared, Kevin Retzke +1’d, 张文涛 +1’d and reshared, Shane Weng reshared, Alex Sherlock reshared, Sascha Lüdecke +1’d, Jonathan Bullock +1’d, Sten Aksel Heien reshared, Paulo Jerônimo +1’d, Anthonny Querouil reshared, Dave Campbell reshared, Leif Gruenwoldt +1’d and reshared, Søren Jones +1’d, Edmund Haselwanter +1’d, John Zoidberg +1’d, Ophir Radnitz +1’d, Italo Penna +1’d and reshared, Peti Koch reshared, Daniel Faust +1’d, cesare cugnasco +1’d, Tong Sun reshared, Jason Lee +1’d, Ding-Yi Chen +1’d, Aditya Raj Bhatt +1’d, sebastien rey coyrehourcq reshared, Martin Pool +1’d, Thomas McDermott +1’d and reshared, Easytouch reshared, Stéphane Gourichon reshared, Günter Zöchbauer +1’d, Timo Ollech +1’d, Antoni Silvestre Padrós +1’d, Dmitry Afanasiev +1’d and reshared, William Chambers reshared, Mani B +1’d, Anton Leontiev reshared, Fabricio Godoy +1’d, Gianluca Scacco reshared, Jeffrey Cardona +1’d, Brian Leathem +1’d, Samuel Bancal reshared, Jose Torres +1’d, Sebastian Peters +1’d, Ștefan Suciu +1’d, Roman Frołow +1’d and reshared, John Jelinek +1’d, Holger Joest reshared, Agam Brahma +1’d, Too simple, Sometimes naive +1’d, Jared Morgan +1’d, DeWitt Clinton +1’d, Alexander Zobkov +1’d
  • 7 of 7