DIG ASCIIDoc Cheat Sheet:
(by Emily Anderson, Spring 2012 intern at Berklee College of Music)

NOTE: With the exception of text formatting, all formatting statements begin and end with line breaks.

NOTE: Unless otherwise instructed, all AsciiDoc commands should be left justified. This is not always necessary, but for the sake of simplicity, assume it usually is.

Sections

Header

Up to now, DIG tends to use the 1st level section instead of the Header.

Written as:

text text text

=========

Preamble

This is rarely used in the current documentation.

Text between header and first section

Differentiated only by line breaks both before and after the text

Sections

-- That appear in the table of contents

Written as:

Section 1 - Level 1

------------------------

Section 1 - Level 2

~~~~~~~~~~~~~~

Section 1.1 - Level 3

^^^^^^^^^^^^^^^^^^^

Note: The punctuation denoting sections beneath the text must be the same length as the text itself - neither longer nor shorter.

For example, these will not display properly:
Section Title

-----------------------

Section Title

-----

Sections

-- That do not appear in the table of contents

Level 4 --- really just one step up from bolding the text

Written as:

Section text

+++++++++

Blocks

Blocks are not generally used, with the rare exception of the Listing Block.

Listing block

-------------------------------

text text

-------------------------------

Example Block

===========

Example Block

===========

Literal Block

…......................

text text text

….....................

Comment Block

//////////////////////

comments!

/////////////////////

Text Formatting

Bolded Text

Enclosed in asterisks

*bolded text*  -- bolded text

Monospaced Text

Enclosed in backticks

`monospaced text` -- monospaced text

Italicized/Emphasized Text

Enclosed in underscores


_italicized/emphasized text_ --
italicized/emphasized text

Lists

Note: A space must be inserted between the bullet (1, ., *) and the text. If there is not space, it will not display properly

Numbered Lists

Written as:

1. Text text text

2. Text text text

Can alternatively be displayed with periods instead of explicit numbers:

. text text text

. text text text

Bulleted Lists

Written as:

* list list list

* list list list

More complex lists...

They do not appear frequently thus far in the DIG documentation...but when they do:

Numbered / bulleted lists:

1. Text text text

2. Text text text

* Text text text

3. Text text text

Nested, bulleted lists

Written as:
* List list list

* list list list

** List list list

** List list list

* List List list

Will render as:

  • List list list
  • list list list
  • List list list
  • List list list
  • List List list

Adding Blocks to Lists

A plus “+” must be inserted on an otherwise empty line between list items and the block both before and after the block begins and ends. This applies to all types of blocks including comment blocks.

Example:
1. list list list

2. list list list

+

block block

block block

+

3. list list list

Insert

Images

Note: It is mandatory that the square brackets be present at the end regardless if they contain any content otherwise the image will not display

image::<target>[attributes]

Example from Robert:

image::media/due_date_display.png[]

Example with Attributes:

image::Picture7.png["Running the Staff Client Installer"]

Tip / Note / Caution

Command must be in all caps unless written in the alternate, bracketed style.

Written as:

TIP: Text text text text

NOTE: Text text text text

CAUTION: Text text text

WARNING: Text text text

Can also be written as:

[Note]

text text text text

[Caution]

text text text

Links

Written as:

link[attributes]

Example:

http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[troubleshooting guide]

Tables

Tables are very rarely used in current DIG documentation

A Basic Table

Written as:

|===

| column 1, row 1 | column 2, row 1 | column 3, row 1

| column 1, row 2 | column 2, row 2 | column 3, row 2

| column 1, row 3 | column 2, row 3 | column 3, row 3

|===

To add a header, which will manifest itself in the first row, write:

[options=“header”]

|===

| header, column 1 | header, column 2 | header, column 3

| column 1, row 2   | column 2, row 2   | column 3, row 2

| column 1, row 3   | column 2, row 3   | column 3, row 3

Note: There does not appear to be a limit to the number of spaces between the | differentiating columns and the text on either side.

For example, a three-column row can be written both of the following ways and render the same:

|column one|column two|column three

|     column one    |    column two     |   column three  

Note: To create a table, it needs to start and end with “|===”

You can add a seemingly unlimited number of equal signs after the vertical bar, but must have a minimum of three for the table to display properly.

Example of how to run ASCIIDoc in the command line (asciidoc utilities must be installed on machine before this will work):

asciidoc -a data-uri -a icons -a toc -b html5 your_filename.txt