AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

Any text editor can be used. Some websites, like Github, render AsciiDoc files directly into HTML.

To get use on it, We can refer trough an IDE with the corresponding plugin, or we have to install it localy on the computer.

IntelliJ AsciiDoc Plugin

A plugin for the IntelliJ platform (IntelliJ IDEA, RubyMine, etc.) that provides support for the AsciiDoc markup language. It also supports Antora, the documentation CMS build with AsciiDoc.

You can install the plugin (named “AsciiDoc”) from the plugins section inside your JetBrains IDE or download it from the JetBrains Plugin Repository.

Features

• Recognizes the AsciiDoc file extension (.adoc, .asciidoc, .ad)
• Provides a two-pane AsciiDoc preview editor based on AsciidoctorJ with live preview.
• Toolbar and context menu for basic formatting and to create tables.
• Refactor Markdown to AsciiDoc: Right click on a file, or use the Refactor menu, and the Markdown document will be replaced by the AsciiDoc equivalent. Also, supports undo if the user is not happy with the result!

AsciiDoc Installation

Installing from the GitHub repository

The AsciiDoc repository is hosted by GitHub. To browse the repository go to https://github.com/asciidoc/asciidoc-py3. You can install AsciiDoc from the repository if you don’t have an up to date packaged version, or you want to get the latest version from the master branch:

• Make sure you have Git installed; you can check with:$ git --version
• Go to the directory you want to install AsciiDoc into and download the repository. This example gets the 9.0.3 tagged release:$ cd ~/bin $ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-9.0.3 $ git checkout 9.0.3

You now have two choices: you can run asciidoc locally from your repository or you can use autoconf(1) and make(1) to perform a system-wide install.

Running asciidoc from your local copy

Create a symlink to the AsciiDoc script in a search PATH directory so it’s easy to execute asciidoc from the command line, for example:

$ ln -s ~/bin/asciidoc-9.0.3/asciidoc.py ~/bin/asciidoc
$ ln -s ~/bin/asciidoc-9.0.3/a2x.py ~/bin/a2x

Use the git pull command to update your local AsciiDoc repository.

Installing asciidoc for all users

Create configure using autoconf(1); use configure to create the Makefile; run make(1); build the man pages; install:

$ autoconf
$ ./configure
$ make
$ sudo make install

To uninstall:

$ sudo make uninstall

Prepackaged AsciiDoc installation

The following platform-specific AsciiDoc packages are available:

Fedora Linux

AsciiDoc is included in Fedora Extras, which is available in the default Fedora installation. To install asciidoc, execute the following command:

$ yum install asciidoc

Ubuntu / Debian

AsciiDoc is included in Ubuntu / Debian package manager. To install, execute the following command:

$ apt install asciidoc

macOS Homebrew

AsciiDoc has been packaged in homebrew and is installable using the following command:

$ brew install asciidoc

See also Packager Notes in the AsciiDoc User Guide.

Overview and Examples

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 using the asciidoc(1) command.

The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and DocBook markups. DocBook can be post-processed to presentation formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript using readily available Open Source tools.

Example Articles

• This XHTML version of the AsciiDoc User Guide was generated by AsciiDoc from this AsciiDoc file.
• Here’s the same document created by first generating DocBook markup using AsciiDoc and then converting the DocBook markup to HTML using DocBook XSL Stylesheets.
• The User Guide again, this time a chunked version.
• AsciiDoc generated this stand-alone HTML file containing embedded CSS, JavaScript and images from this AsciiDoc article template with this command:asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
• The same AsciiDoc article template generated this HTML 5 (the toc2 attribute puts a table of contents in the left margin) from this command:asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt
• The same AsciiDoc article template produced this HTML file and this PDF file via DocBook markup generated by AsciiDoc.

Reference:

https://github.com/asciidoctor

https://asciidoctor.org/

https://asciidoc.org/