Skip to content

Latest commit

 

History

History
177 lines (137 loc) · 5.98 KB

gsg_asciidoc_quickstart.asciidoc

File metadata and controls

177 lines (137 loc) · 5.98 KB
Raw

AsciiDoc Quickstart

AsciiDoc is a text document format for writing (among other things) books, ebooks, and documentation. The main advantages of AsciiDoc are that it is easy to use and plays well with O’Reilly’s publishing process. It’s similar to wiki markup — if you can write a Wikipedia article, then you’re pretty much 90% of the way there. This Asciidoc cheat sheet covers a lot of the nitty-gritty, but the following sections will give you an overview of the markup you’ll use most frequently.

Note

You can get the complete nitty-gritty on how O’Reilly uses AsciiDoc from our official AsciiDoc guidelines. You’ll need to enter "guest" as the username, leave the password blank, and then navigate to the "pdf" directory to download the docs. In addition, the sample chapter with markup is particularly helpful in explaining how things work.

You can create and edit AsciiDoc in any text editor, and then paste it into the wiki to push it into our system. If you’re on Windows, you can use Notepad (or anything you want, really). If you’re on a Mac, you can use TextEdit, TextMate, or any of a number of choices. The important thing is that you use the AsciiDoc markup.

Here are some links to AsciiDoc books that you can use for reference:

Inline Elements

Here’s some some italic and some monospaced (aka "constant-width" or "CW") text:

Here's some some _italic_ and some +monospaced+ (aka "constant-width" or "CW") text:

Backticks can also be used for literal (CW) text, for example: ls -al:

Backticks can also be used for literal (CW) text, for example: `ls -al`:
Warning

Using inlines in AsciiDoc can be tricky.

Delimiters may not be interpreted as intended if they don’t abut whitespace on both sides; the fix for this is to double them up, as explained under ``Constrained and Unconstrained Quotes'' in the AsciiDoc User Guide. For example, compare how these render in the PDF: +foo+ bar vs. foo bar

Hyperlinks

To add a hyperlink, just type the URL followed by the description in brackets. Do not put a space between the brackets and the URL. Here’s an example:

http://oreilly.com/[O'Reilly Media Website]
http://www.makezine.com/[Makezine]
https://github.com/odewahn/codebox2/blob/master/code/fractal_barnsley.pde[Fractal Example in Processing]

Notes, Warnings, and Sidebars

If you need to add a note or warning, here’s the format:

[NOTE]
===============================
O'Reilly Animal books traditionally make no distinction between the
DocBook +<note>+, +<tip>+, and +<important>+ elements.
===============================

.Add a Title
[WARNING] .Add a Title
===============================
O'Reilly Animal books traditionally make no distinction between the
DocBook +<warning>+ and +<caution>+ elements.
===============================

Here’s a Sidebar:

.Titled vs. Untitled Blocks
****
O'Reilly house style generally uses titles only on formal blocks
(figures, tables, examples, and sidebars in particular). Although
AsciiDoc supports optional titles on many other blocks, these
generally are not appropriate for O'Reilly books.

Conversely, _omitting_ a title from a sidebar is generally not
conformant to O'Reilly style. If you have questions about whether
content belongs in an sidebar vs. admonition vs. quote or other
element, please consult with your editor.
****

Code

Enclose code samples inside 4 consecutive minus signs ("-"), like this:

 ----
     if (x < X_MIN) {
        X_MIN = x;
     }
     if (x > X_MAX) {
       X_MAX = x;
     }
     if (y < Y_MIN) {
       Y_MIN = y;
     }
     if (y > Y_MAX) {
       Y_MAX = y;
     }
 ----

You can also use the AsciiDoc "include" macro to pull in code files:

 ----
 include::code/example.c[]
 ----

Bullet lists

Use asterisks ("*") to create bullets. ou can indent items by using multiple asterisks:

* Lorem ipsum dolor sit amet, consectetur adipiscing elit.
* Nulla blandit eros eget velit bibendum placerat.
** Pellentesque id justo ultrices est pharetra suscipit.
** Cras nec magna a lectus consequat varius.
* Phasellus tempor lacinia neque, et scelerisque lectus luctus id.

The list will look like this:

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit.

  • Nulla blandit eros eget velit bibendum placerat.

    • Pellentesque id justo ultrices est pharetra suscipit.

    • Cras nec magna a lectus consequat varius.

  • Phasellus tempor lacinia neque, et scelerisque lectus luctus id.

Numbered lists

Use periods (".") to create a ordered (i.e., "1, 2, 3, …​") lists:

. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
.. Nulla blandit eros eget velit bibendum placerat.
.. Pellentesque id justo ultrices est pharetra suscipit.
. Cras nec magna a lectus consequat varius.
. Phasellus tempor lacinia neque, et scelerisque lectus luctus id.

Here’s how it will look:

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    1. Nulla blandit eros eget velit bibendum placerat.

    2. Pellentesque id justo ultrices est pharetra suscipit.

  2. Cras nec magna a lectus consequat varius.

  3. Phasellus tempor lacinia neque, et scelerisque lectus luctus id.

Simple Tables

Here’s the basic format for creating tables:

.An example table
[width="40%",options="header"]
|=============
|col 1| col 2| col3
|1  | 2 | 3
|4  | 5 | 6
|7  | 8  | 9
|=============

It will look like this:

Table 1. An example table
col 1 col 2 col3

1

2

3

4

5

6

7

8

9