quickintro_asciidoc.adoc : just the basics

By: Zack263

Date: September 29th, 2017

Installing from your home directory in Linux (cd ~)

  • This is a quick-reference guide to writing a text document for asciidoc and ascii-doctor.

  • Step 1: Use the below commands in your text document and save it with an .adoc extension on the desktop.

  • Step 2: Use terminal to go to your desktop and execute the asciidoc commands to produce a new html document.

  • Step 3: Finally drag and drop your html doc on your browser to view your converted .adoc document.

  • Note: Notice in the examples of adding css file to the document and the command to add a table of contents.

// Installing asciidoc
sudo apt install asciidoc

// Installing asciidoctor
sudo apt install asciidoctor

Basic Commands for your text document

== and ===     |     === Title Goes next to the equals

*word*         |     * around word bolds the word

1. 2. 3 and    |     Will work as a numbered list.

*              |     similar to numbered list..bullets.

    ----       |     Four dashes before and after text to display code examples.

+ (plus sign)  |     Does a hard return is like enter

http://surftopctech.com[PCTech MainPage] | pasting the link first[then the description between the brackets] will create a link.

Example Link: PCTech MainPage


// Control + t - for terminal and cd Desktop to move to where your files are.
// Now copy and paste the below asciidoctor command

// Remember To:

    A. Editing the proper css file

    B. Edit the proper desktop path

    C. Edit the proper file name with .adoc extension.

// Note: Use pwd to see your path to desktop; Change path: /home/z/Desktop to your desktop path.

// asciidoctor command here:
asciidoctor -a stylesheet=gm.css -a stylesdir=/home/z/Desktop yourfilenamehere.adoc
  • Your html file will appear on the desktop and drag and drop it on your browser to view it (example min browser).

  • To repeat the process with a different css file make sure to delete or move the current html file first.

Further AsciiDoc Terminal Converting Examples

// Convert to a stand alone regular HTML Document
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt

// Converting to HTML document with a cool Table Of Contents on the left
asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt

Converting to PDF

// check for ruby --version
ruby --version

// install
gem install --pre asciidoctor-pdf
gem install coderay pygments.rb

// verifies install
asciidoctor-pdf -v

// example execution in terminal
asciidoctor-pdf example.adoc

// Source Link:

More content at: zack263.neocities.org