- Home Instant Answers AsciiDoc Cheat Sheet Next Steps. This is the home page for your Instant Answer and can be.
- An AsciiDoc processor parses the document and translates it into a backend format, such as HTML, ePub, DocBook or PDF. AsciiDoc ships with a set of default templates in the tin, but you can customize the templates or create your own to get exactly the output you want. We’ll cover the most common usages of the processor in this document.
Asciidoc FX is a book / document editor to build PDF, Epub, Mobi and HTML books, documents and slides. AsciidocFX is also a winner of Duke’s Choice Award 2015. AsciidocFX - Duke’s Choice Award 2015 winner. Real-Time Preview. Multi-platform (Windows, Mac, Linux). For manuals and guides, Wikis are an excellent way of organizing content. Yet, they often don't work as well for larger articles or books because individual content is spread across many pages and the reader has to click around. Additionally, when you want to read online content while in a place where you cannot get an Internet connection (like, reading on the plane), another mode of content.
That’s what experience has conditioned us to believe.
But, we can’t just avoid it, especially in the tech industry.We must write.Even the most brilliant software is useless without good documentation.If the users fail, so does the project.
Unless your UI discoverability is really good, saying “the feature isn’t documented” is the same as saying “the product can’t do it.”
In other words,
Live and die by documentation.
Then why, oh why, do we make it more difficult by burying the content in XML schemas like DocBook, allowing complex word processors to distract us or wasting time battling with finicky WYSIWYG editors?
Imagine if writing documentation was as simple as writing an email.
That’s the idea behind lightweight markup languages such as AsciiDoc.They offer a plain-text syntax, embellished with subtle, yet intuitive markup, that’s designed for humans to read, write and edit in raw form.The natural feel of the syntax keeps you focused on the content.Best of all, the plain text can quickly and easily be translated into output formats such as HTML5 for presentation.
In this introduction to AsciiDoc, we’ll cover what it is, why it’s valuable and what sets it apart from alternatives such as Markdown.You’ll discover that the key to escaping the agony of writing documentation is dropping the angle brackets that are burying the knowledge you have to share.
To learn how to reduce the work of writing and publishing content—whether it’s notes, documentation, articles, books, web pages or good ol’-fashioned prose—and attain writing zen, or to simply set the ideas locked in your head free, read on.
What is AsciiDoc?
A mature, plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more.
A text processor and toolchain for translating AsciiDoc documents into various formats (called backends), including HTML, DocBook, PDF and ePub.
AsciiDoc belongs to the family of lightweight markup languages, the most renowned of which is Markdown.AsciiDoc stands out from this group because it supports all the structural elements necessary for drafting articles, technical manuals, books, presentations and prose.In fact, it’s capable of meeting even the most advanced publishing requirements and technical semantics.
Serving as testament of this fact, many O’Reilly authors including Matthew McCullough, Tim Berglund, Simon St.Laurent, Matt Neuburg and Ian Darwin have used AsciiDoc to write their books for that iconic technical library.
From the very beginning, AsciiDoc was designed to be a shorthand replacement for DocBook, one of the formats AsciiDoc can generate.AsciiDoc can also produce beautiful HTML5, PDFs, eBooks, man pages and even slide decks.It has you covered from first draft to publishing.
Now that we’ve established what AsciiDoc is, let’s consider why we need it.
As humans, we have no difficulty talking or thinking.In fact, we’re fluent in it.It’s an activity that just happens whenever a thought comes to mind.
When it’s time to write our thoughts down, we struggle to find the words—or, at least, how to arrange and organize them.That damn inner critic disrupts the stream of consciousness we coast on while talking or thinking.
It’s reasonable to conclude that writing is just hard.
On writing: e-mail vs documents
Writing e-mail is easy.We do it all the time.Every day, we respond to dozens of e-mail and social media messages.That involves communication through writing.That’s right, writing!
Yet, amid the flurry of typing that occurs when we respond to an e-mail, we hardly even realize we’re doing it…and fluently!
Most people are OK with writing e-mails.They don’t consider this writing.There’s no writer’s block.Someone asks you a question, you [press] reply and type away.
So why do we struggle to write documents?
The main reason we struggle is because we don’t write documents the same way we write e-mail.Instead, we allow ourselves to get distracted by complex word processors, bury the content in XML schemas like DocBook, or battle with finicky WYSIWYG editors.How did we get ourselves into this mess?
Word processors, the real writer’s block
When you’re in the writing (i.e., typing) phase, you want the words to flow onto the screen with minimal distractions and interruptions.Flow, not just time, is essential.
Most word processors excel at distracting you from writing.The result: you write less (ironic, huh?).
In a word processor, before you can type the first word on a blank white screen, you’re forced to think about what font family you want, what font size you want, what lines spacing you want and so on.Once you do get going, auto-correct, spelling and grammar suggestions entice you to backtrack and lose your next thought.“Smart” quotes and auto-linking messes with the text as fast as you can enter it.If you paste text, it likely gets added to the document with a different font family, size and even color.
Let’s not even talk about inserting source code.The designers of word processors clearly did not.
After burning time fighting with its interface, you rightfully conclude that the word processor is trying to sabotage your writing process.
Use what you know
What if you could write documentation like you write e-mail?
Imagine being able to forget about layout, typesetting, styling (and even some semantics) and just write.That’s the idea behind lightweight markup languages such as Markdown and AsciiDoc.
Here’s how John Gruber introduced Markdown (in March 2004):
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.
A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
The single biggest source of inspiration for Markdown’s syntax is the format of plain text e-mail.
Similarly, here’s how Stuart Rackham introduced AsciiDoc (2 years earlier):
You write an AsciiDoc document the same way you would write a normal text document.There are no markup tags or weird format notations.AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats.
These languages are designed to enable humans to write documents, and for other humans to be able to read them, as is, in raw form.
It’s a plain text syntax…I know this!
Compare that to the same document written in DocBook:
While DocBook (and HTML) may not be complex, they fail the readability test.
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.
AsciiDoc gets us back to what’s important: writing.You can drop those angle brackets, but you don’t have to drop the semantics.And it’s a syntax a human can actually edit, efficiently.
Use AsciiDoc for document markup.Really.It’s actually readable by humans, easier to parse and way more flexible than XML.
Here’s the really great thing about AsciiDoc.Worse case scenario, you convert it to DocBook as a common exchange format.DocBook is the “no lock-in” exit path for AsciiDoc.You decide AsciiDoc doesn’t work out, you can bail on it without losing a word.No need to invent another format.That’s why so many people are going all in on it.
Who’s using AsciiDoc?
AsciiDoc is not as widely adopted as Markdown, but it’s used in some pretty serious places. Here are a few notable examples:
O’Reilly and MakerPress
GitHub supports AsciiDoc syntax in repositories, wikis and gists (powered by Asciidoctor)
NFJS, the Magazine is produced from articles written in AsciiDoc Town of salem crack.
Context and Dependency Injection for the Java EE Platform (CDI)
Specification (AsciiDoc source)
Website (AsciiDoc source)
Golo Programming Language Guide (AsciiDoc source)
Neo4j graph database project (AsciiDoc source)
Phusion Passenger Users Guides (AsciiDoc source)
Git user manual (AsciiDoc source)
Enterprise Web Development: From Desktop to Mobile (AsciiDoc source)
Bintray REST API and User Guide
These examples are more than just testimonials.They should give you ideas about how to be successful with AsciiDoc for your own project.
The zen of writing AsciiDoc
AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets.In other words, it’s about discovering writing zen.
It produces beautiful output (HTML, DocBook, PDF, ePub and more)
AsciiDoc is easy to write and easy to read (in raw form).It’s also easy to proof and edit.After all, it’s plain text, just like that familiar e-mail.
The AsciiDoc syntax is intuitive because it recognizes time-tested, plain text conventions for marking up or structuring the text.The punctuation was carefully chosen to look like what it means.A user unfamiliar with AsciiDoc can figure out the structure and semantics (i.e., what you mean) just by looking at it.Best of all, it only requires a text editor to read or write.
AsciiDoc allows you to focus on the actual writing and only worry about tweaking the output when you are ready to convert the document.The plain-text of an AsciiDoc document is easily converted into a variety of output formats, beautifully formatted, without having to rewrite the content.
Copy text from an e-mail into a document and see how quickly you can turn it into documentation.Almost immediately, you’ll find your writing zen and enjoy the rewarding experience of sharing knowledge.
With an understanding of what AsciiDoc is and why it’s so desperately needed, you’re encouraged to delve into the AsciiDoc syntax covered in the AsciiDoc Writer’s Guide.If you’re just looking for a cheat sheet, check out the AsciiDoc Quick Reference.Hopefully you’ll agree the syntax just makes sense.
Follow the links on this page to learn about the AsciiDoc markup language, Asciidoctor toolchain and the Asciidoctor integrations.You’ll also find tips on how to be most productive when writing with the AsciiDoc syntax.
|Can’t find the information you need? Reach out to project members and users via the discussion list or the real-time chat.|
Using AsciiDoc and Asciidoctor to write documentation (article by vogella)
Get Started with Asciidoctor
Now, let’s setup and use the Asciidoctor toolchain!
Write with AsciiDoc
The documentation for the AsciiDoc language as it’s implemented in Asciidoctor.
An overview of the AsciiDoc syntax you’ll likely need to structure and format a document.
A comprehensive tutorial with examples that show you how to use the AsciiDoc syntax.
Style tips and recommended practices for writing an easy to read and convert document.
A template containing the most common content structures and markup used in an AsciiDoc article document.
Learn how to create diagrams and ASCII art in your AsciiDoc documents using PlantUML, Graphviz, ditaa, and Shaape.
Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, and EPUB 3. This Ruby library is often referred to as Asciidoctor core.
AsciidoctorJ bundles all gems that are required for executing Asciidoctor and wraps it into a Java API so that Asciidoctor can be used in Java like any other Java library.
Asciidoctor PDF is a native PDF converter for AsciiDoc. We’re talking AsciiDoc direct to PDF! Learn how to install Asciidoctor PDF and use it to convert your AsciiDoc documents to PDF.
Asciidoctor EPUB3 is a native EPUB3 converter for AsciiDoc. Learn how to install Asciidoctor EPUB3 and use it to convert your AsciiDoc documents directly to EPUB3 and Amazon’s KF8/Mobi format for Kindle.
Asciidoctor reveal.js is a converter for Asciidoctor and Asciidoctor.js that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the reveal.js presentation framework.
Build Automation Plugins
Migrate to Asciidoctor
Contribute to Asciidoctor
“I have code I’d like to contribute!” Then checkout this guide ⇒ How do I submit code to the project?