To quote the AsciiDoc Syntax Quick Reference Guide (which you should bookmark*!*):
AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. This guide is a quick reference for the common AsciiDoc document and text formatting markup.
If you look through the guide, you'll see that it's a file format which is quite similar to Markdown, supporting paragraphs, formatted text, headers, sections, section titles, lists, links, images, code, tables, videos, and so much more.
What's more, the format is consistent and predictable, as it has a definitive standard. This is in stark contrast to Markdown, which has a series of (often competing) standards, such as GitHub Flavoured Markdown, and Daring Fireball.
AsciiDoc is a robust, text-based file format, which you can use to create even the most sophisticated technical documentation, able to be exported to a range of modern file formats. Have a look through the quick reference guide, and the rest of the official AsciiDoc documentation to learn more.
To contribute to the documentation, you're only going to need 3 things; these are:
- A text editor with AsciiDoc syntax support available.
- An AsciiDoc previewer.
- AsciiDoc documentation
Let's step through each one.
Just like writing in any other format or computer language, you're going to need a text editor or an IDE. And as you're a developer, you'll already have one, and it likely supports AsciiDoc already. If not there should be a plugin available for it. Here are some of the text editors and IDEs that we recommend.
If you're using VIM (or VI), there are two plugins that you can make use of; these are dahu/vim-asciidoc, and matcatc/vim-asciidoc-folding. vim-asciidoc provides enhanced editing support for Asciidoc files. vim-asciidoc-folding allows vim to enable folding asciidoc files.
Alternatively, if you want both of these, plus some extra setup ready to go, you can use the Vim for Technical Writers repository.
The repository has a .vimrc file that installs both plugins, enabling them only when editing Asciidoc files.
SublimeText doesn't come with native support for AsciiDoc, but you can install the AsciiDoc package which provides it. Once you do that, you'll have a range of AsciiDoc editing functionality available, including:
- Snippets
- Syntax Highlighting
- Keymaps
- Attribute completion
- Display document and section titles in the local symbol list
In recent months, Atom's been gaining significant traction. Written primarily by the team at GitHub and supported by a massive community around the world, and packed with a wide range of features out of the box, it's easy to see why.
If it's your text editor of choice, install the asciidoc-assistant package. This package is a meta-package that takes care of installing a range of plugins, which to give you full AsciiDoc support.
These are:
- language-asciidoc: This package adds syntax highlighting and snippets to AsciiDoc files.
- asciidoc-image-helper: This package facilitates insertion of images in an AsciiDoc document.
- asciidoc-preview: This package allows Atom to show the rendered HTML of the AsciiDoc content in the current editor.
- autocomplete-asciidoc: This package provides AsciiDoc language auto-completions in Atom.
Note: to view images in the preview pane, you have to set the imagesdir attribute in the AsciiDoc plugin's preferences.
To do that:
- Open the Preferences pane for the "asciidoc-preview" package.
- In the "Default Attributes" field, under "Settings", add the absolute path to the image directory for one of the modules, at the end of the existing attributes.
Unfortunately, you cannot reference multiple image directories.
If you're on the Microsoft Windows platform or love the Visual Studio environment — and in particular the new "Code" editor/IDE — then you'll be happy to know that it supports AsciiDoc as well. If you install the AsciiDoc plugin, then you'll get some basic functionality, including:
- Live preview.
- Syntax highlighting.
- Open Preview to the Side.
- View Symbols and Go to Symbol actions.
Note: I’m not, currently, aware of how to enable rendering images in the preview pane.
If you're a fan of IDEs over text editors, in particular, the JetBrains IntelliJ platform, then make sure you install the AsciiDoc plugin, available, from the JetBrains repository.
It provides a minimal set of functionality when editing AsciiDoc files, which includes:
- Live Preview (show editor and preview, the editor only, and preview only).
- Basic formatting toolbar (bold, italics, mono-spaced).
- Code folding.
- Syntax highlighting.
- Convert non-AsciiDoc files to AsciiDoc.
Note: to view images in the preview pane, you have to set the imagesdir attribute in the AsciiDoc plugin's preferences.
To do that:
- Open the Preferences pane and filter by
"AsciiDoc". - In the "Attributes" field, add a new entry, where "Key" is set to
imagesdirand "Value" is set to the absolute path to the image directory for one of the modules. - Click either "Apply" or "OK".
Unfortunately, you cannot reference multiple image directories, whether by using a regular expression, nor can you specify imagesdir multiple times.
If you're not already using one of these text editors of IDEs, don't feel the need to change to them, just because they're what we recommend. It's possible that your existing text editor or IDE already has an AsciiDoc plugin. And it makes far more sense to continue using what you already know, instead of learning an entirely new tool.
Once your text editor or IDE is ready to work with AsciiDoc then, assuming it doesn't already support previewing AsciiDoc, you’ll need a way to preview the changes you’re making to ensure that they render as you expect.
For that, assuming that you’re using one of Google Chrome, Mozilla Firefox, or Opera, you need to install the AsciiDoc Live Preview plugin. When installed, enable the AsciiDoc Live Preview plugin, and you will see AsciiDoc files rendered as HTML in the browser.
## AsciiDoc Documentation
As with anything of a technical nature, you need documentation, because there’s going to come a time that you will need to refer to it. So too with AsciiDoc. Here are a set of links to documentation that you can bookmark and use on a regular basis: