Introduction

AsciiDoc is a lightweight mark up convention for creating consistently formatted text documents. Unlike other mark up systems, AsciiDoc usually makes documents more human readable than not.

It is similar to Wikipedia’s mark up conventions and shares many features exactly. However, it is focused more on source document readability and less on HTML and tags appearing in your text. Despite this clear reading, easy writing syntax, the great thing about AsciiDoc is that it can be automatically turned into a very sensible HTML document.

Running AsciiDoc

To convert text documents to html:

/pro/asciidoc/asciidoc document.txt

This should produce a document called "document.html".

Actually on most workstations now you don’t have to specify the path. Just…

$ asciidoc document.txt

…should work from anywhere. However, if there is some advanced feature you require, there is probably a later version of AsciiDoc in the directory shown above.

Title

The first thing an AsciiDoc formated document needs is a title. Basically you just underline the top line with equals like so:

Basic AsciiDoc For Abagyan Lab Members
======================================
Your Optional Name <optional@email.edu>

Now onto some content. The blank line above should be included.

Headings

AsciiDoc text source Output HTML
== A Grand Heading
Headings are important! Some text goes here and it works just like
you'd hope it would with your favorite text editor.

== Another Way ==
This way looks nice but it is more annoying to type and edit. The
results are the same as above.

A Grand Heading

Headings are important! Some text goes here and it works just like you’d hope it would with your favorite text editor.

Another Way

This way looks nice but it is more annoying to type and edit. The results are the same as above.

Lists

AsciiDoc text source Output HTML
Lists are common in notes and helpful documents. They can:

* Help you remember things.
* Enumerate your options.
* Help you make other recursive lists:
  - Make lists within lists.
  - You can go many levels deep.
  - See full docs for details. It's not hard.
* Formulate a plan of future events.

Some lists are ordered:

. Install Ubuntu
. Install libpng
. Install libbz2
. Make fancy link reassignments.
. Install ICM
. Enjoy!

Lists are common in notes and helpful documents. They can:

  • Help you remember things.

  • Enumerate your options.

  • Help you make other recursive lists:

    • Make lists within lists.

    • You can go many levels deep.

    • See full docs for details. It’s not hard.

  • Formulate a plan of future events.

Some lists are ordered:

  1. Install Ubuntu

  2. Install libpng

  3. Install libbz2

  4. Make fancy link reassignments.

  5. Install ICM

  6. Enjoy!

When you make lists, make sure you separate the list items with a blank line. There are various bullet styles and they can be nested too but that’s not worth worrying about yet.

Special things

AsciiDoc text source Output HTML
One of my *favorite* things is *emphasized*. If you're _Italian_ you
might appreciate _italics_. There are lots of tricks like this, but
don't confuse yourself. *Stick to the basics!*

Chemistry people sometimes like their Moronic Acid, C~30~H~46~O~3~,
with subscripts.

And the very same people often do crazy stuff like: e^i&pi;^+1=0

Many nerdy people like to quote computer jargon like
`#!/pro/icm/icm/icm -s`. This `monospaced` presentation is a good way
to capture the literal essence. The mnemonic here is that back quotes
usually signify a literal thing executed in a shell in many
programming environments.

One of my favorite things is emphasized. If you’re Italian you might appreciate italics. There are lots of tricks like this, but don’t confuse yourself. Stick to the basics!

Chemistry people sometimes like their Moronic Acid, C30H46O3, with subscripts.

And the very same people often do crazy stuff like: e+1=0

Many nerdy people like to quote computer jargon like #!/pro/icm/icm/icm -s. This monospaced presentation is a good way to capture the literal essence. The mnemonic here is that back quotes usually signify a literal thing executed in a shell in many programming environments.

Blocks

AsciiDoc text source Output HTML
Sometimes you're writing stuff like this long-winded text and you need
to stop to show the user something, maybe a block of code. You can do
this with some dashes. It doesn't matter how many really.

----------------------------------
#!/bin/icm
read pdb "3hag"
display
quit
----------------------------------

And now we're back to long text.

Sometimes you’re writing stuff like this long-winded text and you need to stop to show the user something, maybe a block of code. You can do this with some dashes. It doesn’t matter how many really.

#!/bin/icm
read pdb "3hag"
display
quit

And now we’re back to long text.

If you’re really thinking of a web page, then links are very useful. If not, this is just a consistent way to write them in your text notes that converts well. The basic idea is a link URL followed by text that should be associated with that URL.

AsciiDoc text source Output HTML
For example here is the
http://ablab.ucsd.edu[lab's website]. If it doesn't start with http,
then you can do something like this where I'm linking to
link:./ezasciidoc.txt[a static local file].

For example here is the lab’s website. If it doesn’t start with http, then you can do something like this where I’m linking to a static local file.

Images

AsciiDoc text source Output HTML
Images are done much the same way as links. Basically you just need to
say image before your link and have some alternate text that describes
the image in brackets. Here's an example:

image:./lab_work.jpg[Abagyan Lab Work]

Images are done much the same way as links. Basically you just need to say image before your link and have some alternate text that describes the image in brackets. Here’s an example:

./lab_work.jpg