Writing in AsciiDoc

Atlas supports writing in AsciiDoc, a text document format for writing (among other things) books, ebooks, and documentation. It is similar to wiki markup—if you can write a Wikipedia article, then you’ll have no problem with AsciiDoc. Files ending in .asc or .asciidoc will be converted to HTMLBook when building. AsciiDoc files in Atlas can be edited using the Code Editor.

AsciiDoc Markup Reference

This section illustrates some of the most common elements used in writing technical documentation. The AsciiDoc User Guide and the AsciiDoc cheat sheet are other helpful references, but the following sections will give you an overview of the markup you’ll use most frequently, plus some customized markup that is specific to Atlas.

Text

Regular paragraph text does not need any special markup in AsciiDoc. Just add a blank line both above and below each paragraph, and the first word in the paragraph should not have a space before it. Here are some example paragraphs in AsciiDoc:

This is an example paragraph written in AsciiDoc. See, it's just plain text; no special markup necessary! Do make sure there aren't spaces or manual indentations at the beginning of your paragraph text.

This is a second example paragraph in AsciiDoc. Note that there's a line break and a blank line between paragraphs.

To learn how to add inline markup such as italics to your text see the Inline Markup section.

Chapters

The top of each chapter file should begin with a chapter title preceded by two equals signs. It's good practice to always include a unique ID string above the chapter title, surrounded in double brackets, for example:

[[unique_chapter_id]]
== Chapter Title

Chapter text begins here.

Headings

There are multiple ways to mark up heading levels in AsciiDoc. We've chosen our favorite "delimited" style to show you below, but feel free to use the two-line underlined heading style if you prefer.

Note

The levels described in the AsciiDoc User Guide can be confusing: in AsciiDoc, the document (book) is considered level 0; generally a chapter will be at AsciiDoc level 1 (unless you're dividing the book into parts), and sections within chapters start at AsciiDoc level 3 (which is equivalent to HTMLBook section data-type="sect1").

Top-level heading

Within a chapter, the first and highest heading level uses three equals signs:

=== Top-Level Heading

Second-level heading

This heading level should only follow a top-level heading:

==== Second-Level Heading

Third-level heading

This heading level should follow a second-level heading only:

===== Third-level heading

Parts

If you want to group your chapters into parts, you can do so by creating a new asciidoc file (for example, part1.asciidoc) and then inserting the following part markup:

[[unique_part_id]]
[part]
== Part Title

Once you have created the part file, include it in the Build Contents on the Configure page before the first chapter you wish to be included in the part.

To add introductory text to a part, add this partintro markup after the part title:

[[unique_part_id]]
[part]
== Part Title

[partintro]
--
Insert introductory text here.
--

Prefaces

A preface file should begin with the word preface in single brackets, followed on the next line by two equals signs and the preface title:

[preface]
== Preface Title

Preface text begins here.

Forewords

A foreword file should begin with the word foreword in single brackets, followed on the next line by two equals signs and the foreword title:

[foreword]
== Foreword

Foreword text begins here.

Afterwords

The markup for an Afterword is similar to the preface markup, but it has an additional role attribute with a value of "afterword". Here's the markup:

[preface]
[role="afterword"]
== Afterword

Afterword text begins here.

Dedications

A dedication file should begin with the word dedication in single brackets, followed by a blank line and then the dedication title and text. The title must be present, but it will not render in the output:

[dedication]
== Dedication

This book is dedicated to my cat, Garfield.

Dedication pages render on their own page at the beginning of the book, before the table of contents.

Praise Pages

Praise pages are marked up similarly to Dedications, but you will add a special role="praise" attribute. For each item of praise, use the quote markup (discussed in Quotes):

["dedication", role="praise"]
== Praise for Getting Started with Atlas

[quote, Jane Doe]
____
"This book is awesome."
____

Praise pages render at the beginning of the book, before the title page, and are not included in the regular page numbering of the book.

Glossaries

A glossary file should begin with the word glossary in double brackets, followed by the glossary title and a blank line. Following the blank line should be another instance of the word glossary, this time in single brackets.

Each glossary entry should consist of one glossary term, followed by two colons and a space, then the glossary definition. If you’d like to add an additional paragraph to a glossary definition, add a plus sign ("+") on the following line by itself, and begin the additional paragraph on the line after it.

Here’s an example of the markup:

[[glossary]]
== Glossary

[glossary]
Crawler:: A program used to index documents.
+
See Also Spider

Appendixes

To designate a file as an appendix, simply add the word appendix in single brackets at the top of the file. Immediately below it should be the title of the Appendix. For example:

[appendix]
== Resources

The following list of resources ...

Chapter Contributors

For books with multiple contributors, you may want an author name to appear with each chapter. O'Reilly house style is to place the name of the chapter contributor below the chapter heading, so you can simply add the following markup as a separate paragraph between the chapter title and first paragraph of content:

[role="byline"]
Author Name

When multiple lines are necessary—for example, when you would like to include the author's affiliation—use the [role="byline cont"] markup in a separate paragraph for every line that should follow the first:

[role="byline"]
Author Name

[role="byline cont"]
Author Affiliation

For multiple authors of one chapter, the markup looks like this:

[role="byline"]
Author Name

[role="byline cont"]
Author Affiliation

[role="byline"]
Another Author

[role="byline cont"]
Another Author's Affiliation

You can also use this same markup for forewords, prefaces, and appendixes. Please note that contributor names in a foreword will render preceded by an em dash, since house style places foreword author bylines at the end of the foreword.

Inline Markup

Here are some standard typographical conventions with explanations of how they're commonly used:

_Italic_

Italic text indicates new terms, URLs, email addresses, filenames, and file extensions. The AsciiDoc markup is one underscore character on either side of the text to be italic.

To mark a a few letters of a word in italics, or a word that abuts a non-whitespace character, double up the underscore characters on either side of the text, like this: __Part__ial word i__tal__ic

*Bold*

Bolded text is used to emphasize a word or phrase. The AsciiDoc markup is one asterisk on either side of the text to be bolded.

Warning

O'Reilly Authors

Please note that O'Reilly house style prefers italics for emphasis.

To mark a partial word in bold, or a word that abuts a non-whitespace character, double up the asterisk characters on either side of the text, like this: **Part**ial word b**ol**d

+Constant Width+

Constant width, or monospaced, text is used for code, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. The AsciiDoc markup is one plus sign on either side of the text to monospaced.

To mark a partial word in constant width, or a word that abuts a non-whitespace character, double up the plus signs on either side of the text, like this: ++Part++ial word con++st++ant wid++th++

*+Constant Width Bold+*

Monospaced and bolded text is used to show commands or other text that should be typed literally by the user. The AsciiDoc markup is one asterisk and one plus sign on either side of the text. Note that the asterisk (*) pair should be on the outside and the plus-symbol (+) pair on the inside.

To mark a partial word in constant width bold, or a word that abuts a non-whitespace character, double up the markup on either side of the text, like this: **++Part++**ial word constant w**++id++**th bold

_++Constant Width Italic++_

Monospaced and italicized text indicates where text should be replaced with user-supplied values or by values determined by context. The AsciiDoc markup is one underscore and two plus signs on either side of the text. Note that the underscore (_) must be on the outside and the plus-symbol (+) pair on the inside.

To mark a partial word in constant width italic, or a word that abuts a non-whitespace character, double up the underscore markup on either side of the text, like this: __++Part++__ial word con__++st++__ant width ital__++ic++__

~subscript~

For subscript text, use a tilde character (~) on either side of the subscript text.

^superscript^

For superscript text, use a caret (^) character on either side of the superscript text.

Hyperlinks

For hyperlinks to external sources, just add the full URL string followed by brackets containing the text you'd like to appear with the URL. The bracketed text will become a clickable link in web versions. In print versions, it will appear in the text, followed by the actual URL in parenthesis.

The markup looks like this:

Visit the http://oreilly.com[O'Reilly website]

Note that these will become hyperlinks in online versions, so for fake or example URLs, use +constant width+ or _italic_ markup instead.

Notes, Tips, Warnings, and Cautions

You have the option of using note, tip, warning, and caution elements for supplemental information.

You may also notice that some of the admonitions below have a title. We do support optional titles in admonitions. If you don’t want a title for your note, tip, warning, or caution, just leave out the entire .Tip Title line in the markup below.

The markup for a note looks like this:

[NOTE]
====
Here's some text inside a note.
====

And here’s how it renders:

Note

Here’s some text inside a note.

You’d create a tip with a title like so:

.Tip Title
[TIP]
====
Here's some text inside a tip.
====

…which will yield this result:

Tip

Titled Tip

Here’s some text inside a tip.

Or you could use a warning:

.Warning Title
[WARNING]
====
Here's some text inside a warning.
====
Warning

Warning Title

This is how warnings render. Warnings can be used for including supplemental information in your text. Including a warning title is optional.

Finally, here’s a caution:

[CAUTION]
====
Here's some text inside a caution.
====
Caution

This is how cautions render. Cautions can be used for including supplemental information in your text.

Footnotes

To create a footnote, place the footnote macro directly after the text where the note number should appear, with no space between.1 The content of the footnote should appear within the brackets. Footnotes at the end of a sentence belong after the period:

footnote:[This is a standard footnote.]

Here’s an example of the markup placement in the text:

There should be no spacefootnote:[This is a standard footnote.] between the text and the note number.

For an example of the footnote rendering, see the first paragraph in this section. You should see the content of the note rendering at the bottom of the page.

Quotes

To add a block quote to your text, use the word quote inside single brackets, followed by a comma and the full name of the quote’s author. The text of the quote itself should appear immediately below, with four underscore characters above and below it.

Here’s some example markup, a quote attributed to Benjamin Disraeli (by Wilfred Meynell, according to Frank Muir):

[quote, Wilfred Meynell]
____
Many thanks; I shall lose no time in reading it.
____

And here’s how it renders:

Many thanks; I shall lose no time in reading it.

— Wilfred Meynell

Figures and Other Images

Full figure markup should include a unique ID attribute, so the figure can be cross-referenced (see Cross-References for more info on using cross-references). Please note the figure IDs should be unique throughout the book. Non-captioned figures don’t have ID attributes or figure numbers and are not cross-referenced.

Create a figure with a caption like so:

[[unique_id]]
.A Figure
image::images/tiger.png["An image of a cartoonish tiger head"]

And here’s how it renders:

An image of a cartoonish tiger head
Figure 13-1. A Figure

If you’d like your figure to appear without a caption, just omit the .title line. Please keep in mind that in addition to having no title, these figures will also have no figure number and cannot be cross-referenced in the body of the text.

Here’s the markup:

image::images/screenshot.png["Screenshot of the AsciiDoc website."]

And here’s how it renders:

Screenshot of the AsciiDoc website.

Adding alt text to images

To improve accessibility in your ebook files, please consider adding alt-text to the images. To do this, just add the descriptive text in quotes inside the brackets, which are at the end of the image markup:

[[unique_id]]
.A Figure
image::images/tiger.png["An image of a cartoonish tiger head"]

Adjust image size

While it should not be necessary in most circumstances, you can control the size of an image in the PDF output by adding an absolute value of width or height, like so:

image::images/filename.png[width="2in"]

image::images/filename.png[height="2in"]

Lists

There are three common types of lists; below are the markup and an example of each.

Note

If you're an O'Reilly author, the O’Reilly Style Guide and Word List has more details about when to use which type of list.

Bulleted (aka itemized) lists

Here’s the markup for a bulleted list:

* lions
* tigers
** sabre-toothed
** teapotted
* lions, tigers, and bears
+
Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

The list renders as you’d expect:

  • lions

  • tigers

    • sabre-toothed

    • teapotted

  • lions, tigers, and bears

    Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Note that the final item in the list has multiple paragraphs. As you can see in the markup example, a plus (+) character can be used to add additional paragraphs to a list item.

Ordered (aka numbered) lists

Here’s the markup for a numbered list:

. Preparation
. Assembly
.. Measure
.. Combine
.. Bake
. Applause
+
Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Using the above markup will generate a numbered list:

  1. Preparation

  2. Assembly

    1. Measure

    2. Combine

    3. Bake

  3. Applause

    Use a plus sign (on its own line) with the text below to add multiple paragraphs to a list item.

Note that the final item in the list has multiple paragraphs. As you can see in the markup example, a plus (+) character can be used to add additional paragraphs to a list item.

Labeled (aka variable or term-definition) lists

Here’s the markup for a labeled list:

Term 1::
  Definition/description
Term 2::
  Something else

Labeled lists look like this:

Term 1

Definition/description

Term 2

Something else

Tables

Standard AsciiDoc markup for a simple table follows:

.A Table
[options="header"]
|=======
|P|Q|P^Q
|T|T|T
|T|F|F
|F|T|F
|F|F|F
|=======
Note

Note that a single vertical bar (|) character is used to separate each box in the table. If you’re having a problem with your table columns rendering oddly, make you have that you have the same number of vertical bars for each row.

The table will render with a title and a header row:

Table 13-1. An example table
P Q P^Q

T

T

T

T

F

F

F

T

F

F

F

F

Code

Code blocks (or as the AsciiDoc documentation refers to them, “listing” blocks), are defined using four hyphens above and below the code block content:

----
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890
----

Which will render like this:

Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890

Formal code blocks (titled and cross-referenced)

If you’d like the code block to have a title and be able to cross-reference it, you should use the formal code block markup. As you can see below, you’ll need to additionally surround the code block with four equals signs, a title, and an ID in double brackets:

[[EX1]]
.A code block with a title
====
----
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890
----
====

The results:

Example 13-1. A code block with a title
Hello world!

0        10        20        30        40
1234567890123456789012345678901234567890

Inline formatting within code

If you want to use inline formatting in code—in particular, for typographical conventions such as bold or italic, you can do so by using a passthrough block (see Passthroughs for an explanation of passthroughs). Here’s the markup to use a passthrough with the HTML element <pre>:

++++
<pre data-type="programlisting">hostname $ <strong>date</strong>
<em>Sun</em> Apr  1 12:34:56 GMT 1984</pre>
++++

which renders like this:

hostname $ date
Sun Apr  1 12:34:56 GMT 1984

Syntax highlighting

The Atlas book-building toolchain supports syntax highlighting via Pygments. You need only add [source] above each code block that should include syntax highlighting, and specify the language of the code. For example:

[source,java]
----
int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;
----

This will render in the EPUB, PDF, and KF8 (Kindle Fire only) as follows:

int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;

Here is the markup if you want to add syntax highlighting to a formal code block—note the placement of [source] is the same:

[[id_here]]
.Syntax highlighting sample
====
[source,java]
----
int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;
----
====

Pygments supports a wide variety of languages that can be used in [source]; see the full list available on the the Pygments website. Ebook readers that do not have color screens will still display the highlighting, but in more subtle shades of gray.

Note

The color scheme is consistent across books and cannot be changed at this time.

External code files

There are two ways to include external code files. You can include an external file that is text-only (no markup like line annotations or inline formatting), or you can include an external file marked up with valid XHTML, which can contain inline markup. Callouts will work with either method.

To include an external code file that is text-only (no inline markup besides callouts), use the include:: macro inside of a delimited code block, as shown here:

[source,java]
----
include::code/HelloWorld.java[]
----

For info about using callouts with your external AsciiDoc code file, see Code callouts.

To include an external file that contains inline markup (e.g., line annotations or inline font formatting), use passthrough markup around around the include:: macro, instead of code block delimiters:

++++
include::code/inline_markup.html[]
++++

In the above case, the contents of inline_markup.html would contain only the HTML markup. In our example, which might look something like this:

<pre data-type="programlisting">Roses are <em>red</em>,
   Violets are <em>blue</em>.
Some poems rhyme;
   This one <strong>doesn't</strong>.</pre>

The results will look like this:

Roses are red,
   Violets are blue.
Some poems rhyme;
   This one doesn't.

Code callouts

Code callouts are used to mark specific lines of code with icons keyed to explanatory text outside the code block. These icon pairs function as bidirectional links in electronic PDF and downstream formats (i.e., you can click on the icon in the code to jump to the explanation, and vice versa).2

Here’s the AsciiDoc markup for code callouts:

----
Roses are red,
   Violets are blue. <1>
Some poems rhyme;
   This one doesn't. <2>
----
<1> Violets actually have a color value of +#9933cc+.
<2> This poem uses the literary device known as a "surprise ending."

The output will include callouts numbers in the code, followed by a numbered list, as shown here:

Roses are red,
   Violets are blue. 1
Some poems rhyme;
   This one doesn't. 2

To use code callouts with an external AsciiDoc code file, add the callout text items below the code block, like so:

[source,java]
----
include::code/HelloWorld.java[]
----
<1> This is number one.
<2> This is number two.

Cross-References

All references to titled block elements and book components—figures, tables, examples, sections, chapters, parts, and so on—should be marked up as cross-references, not entered as plain text. Cross-reference markup will become a live hyperlink to the target in digital versions and will resolve automatically if you move numbered elements (figures, chapters, etc.) around while editing.

To insert a cross-reference, follow these steps:

  1. Note the id of the element you are referencing. If the element does not have an id, you will need to add one. For the book to be valid, ids must be unique across the entire book, have no spaces, and not start with a number. For example, a figure id looks like this:

    [[unique_id]]
    .Figure title
    image::images/figure.png[]
  2. Once you have the id, you can insert a cross-reference to that element elsewhere in the text by enclosing the id in double angle brackets, like so:

    <<unique_id>>

The Atlas build system will transform this id into a standard cross-reference (or <xref>) for you: the rendered text will adjust automatically if you later move the target or reword its title, and it will work as a hyperlink in digital versions.

The following table shows the standard text generated from the cross-references in PDF builds.

Table 13-2. Standard cross-reference formats
Target Generated Cross-Reference Text

chapter

Chapter 17

table

Table 4-1

figure

Figure 2-3

example

Example 3-5

sidebar

"Fooing the Bar" on page 23

section

"Inline Macros" on page 14

Here are some live examples (hover over the text in the PDF to locate the hyperlink):

which were generated from this source:

* See <<indexing>> for details.
* The results is shown in <<unique_id>>.

Passthroughs

This section makes several references to “passthroughs.” You can use an HTML passthrough when you’ve got an especially complex piece of markup or you’re trying to do something that AsciiDoc doesn’t support. AsciiDoc supports two types of passthroughs:

Inline passthroughs

For inlines, you can indicate a passthrough at any time by adding this passthrough markup within the text paragraph:

pass:[inline HTML markup here]

See Troubleshooting Inline Markup for examples of inline passthroughs.

Block passthroughs

You can also pass though a block of HTML by adding 4 plus signs above and below the HTML. Here’s the image markup that we used above, passed through as HTML:

++++
<figure id="unique_id" float="none">
<figcaption>A Figure</figcaption>
<img src="images/tiger.png"/>
</figure>
++++

Math Support via LaTeX

Atlas supports math equations set as LaTeX. For inline LaTeX equations, use the latexmath: macro as follows:

The Pythagorean Theorem is latexmath:[\(a^2 + b^2 = c^2\)].

yielding this result:

The Pythagorean Theorem is \(a^2 + b^2 = c^2\) .

For block TeX equations, use a latexmath passthrough as follows:

[latexmath]
++++
\begin{equation}
{x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}}
\end{equation}

++++

And the results:

\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\)

You could also add a title. Use this:

[latexmath]
.The quadratic formula
++++
\begin{equation}
{x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}}
\end{equation}

++++

And get:

The quadratic formula

\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\)

Controlling Line Breaks

Use an inline passthrough to prevent a line break:

pass:[<span class="keep-together">Don'tBreakMe</span>]
Warning

Please do not use AsciiDoc’s mechanisms for forcing line breaks, as these don’t mesh with Atlas’s book building tools.

Indexing

This section describes how to create an automatically generated index in AsciiDoc. We’ve extended indexing in AsciiDoc to include ranges, sees, and see alsos.

Create the index file

To include an index in your book, first create a blank index.asciidoc file and add this single line of text:

== Index

The index entries will be auto-generated during the build process, using the index markers you place in the text, as described in the next section. Just be sure to include the index.asciidoc file in the build.

Syntax

Each index marker is generally surrounded with quotation marks. But for basic index entries without attributes (i.e., without ranges, a “see,” a “see also,” or a “sortas”), you do not need to enclose terms in quotation marks. For example, the following markup is fine:

(((XML, RDF, SPARQL)))

However, if you include any attributes, you must put all entries in quotes as seen below, e.g.:

((("XML", "RDF", "SPARQL", seealso="XQuery")))
Note

For anything not mentioned below, please refer to the AsciiDoc User Guide.

Basic index entry:

((("primary index term")))

Secondary entry:

((("primary index term", "subentry")))

Tertiary entry:

((("primary index term", "subentry", "sub-subentry")))

An index entry with a range:

The future of ebooks is HTML5.((("HTML5", id="ix_html5", range="startofrange")))
In the following pages
...
blah blah blah canvas
blah blah blah local storage
blah blah blah geolocation
...
Learn HTML 5 today!(((range="endofrange", startref="ix_html5")))

An index entry with a “(see)” and no page reference:

Flash has been supplanted by HTML5.((("Flash", see="HTML5")))

An index entry with a “(see also)”:

There are two markup options for "see also" entries.

  • You can embed the seealso with the primary entry. This will render a page number next to the primary entry:

In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", seealso="RepRap")))
  • Or if there’s a subentry, you can embed the seealso entry after the it:

In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", "3-D", seealso="RepRap")))
Warning

Any "(see also)" entries that are nested under primary entries with no page numbers of their own (i.e., primary entries that have subentries) will render with extra indentation.

To alphabetize an index entry differently than the default, use "sortas" to assign a new label to be used for alphabetization. For example:

Makerbot lets you produce your own 3-D trinkets.((("3-D", sortas="three-d")))

1Otherwise you’ll introduce extra space in the text

2The built-in AsciiDoc mechanism is somewhat more limited in that icons are hyperlinked from text to code, but not vice versa. If two-way linking is important to you, consider using a passthrough block (see Passthroughs).