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. AsciiDoc files in Atlas can be edited using the Code Editor.
AsciiDoc files are converted to HTMLBook in Atlas’s backend before generating output formats. Syntax errors for AsciiDoc markup are typically, and unfortunately, cited at line numbers in the generated HTMLBook.
AsciiDoc Markup Reference
This section provides markup examples for some of the most common elements used in writing technical documentation. These examples comprise some of the most common use cases for typical O’Reilly authors, as well as a few examples highlighting markup idiosyncratic to Atlas’s support for AsciiDoc.
Note that Atlas uses a custom, HTMLBook-specific template for Asciidoc. Please consult the AsciiDoctor documentation, for a more complete guide on AsciiDoc syntax, but please be aware that Atlas’s custom implementation may not support all Asciidoctor syntax, or produce the same results.
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 styling (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 above the chapter title, surrounded by 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, but please use the now-standard = heading syntax, as described in the Asciidoctor heading documentation.
The levels described in the Asciidoctor heading documentation 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").
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 TitleOnce 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 data-type 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 data-type foreword in single brackets, followed on the next line by two equals signs and the foreword title:
[foreword]
== Foreword
Foreword text begins here.
[role="byline"]
Some Famous PersonAfterwords
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:
[appendix]
[role="afterword"]
== Afterword
Afterword text begins here.Dedications
A dedication file should begin with the word dedication in single brackets, followed by the dedication title and text. The title must be present and must be "Dedication", but it will not render in the output:
[dedication]
== Dedication
This book is dedicated to my cat, Garfield.Glossaries
A glossary file should begin with the section ID glossary in double brackets, followed by the glossary title and a blank line. Following the blank line should be another instance of the data-type 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 SpiderAppendixes
To designate a file as an appendix, add the data-type appendix in single brackets at the top of the file. Immediately below it should be the title of the Appendix. For example:
[appendix]
[[unique_appendix_id]]
== 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 themes support placing, when appropriate, the name of the chapter contributor below the chapter heading. You can add the following markup as a separate paragraph between the chapter title and first paragraph of content:
[role="byline"]
Author NameWhen 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 AffiliationFor 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 AffiliationYou 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 is to place foreword author bylines at the end of the foreword.
Inline Markup
The following list comprises typographical conventions and O’Reilly house style recommendations for their use.
- 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.
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 be 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 to which you’d like to anchor 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 parentheses.
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 widthor italic markup instead.
Troubleshooting Inline Markup
Using inlines in AsciiDoc can sometimes be tricky. If you’re having problems with inline markup not rendering correctly, or if it’s producing validation errors, check if it’s an issue with nested inlines. Attempting to nest inlines within each other may sometimes result in problems if the markup is done in the wrong order. For example, constant width bold text uses an asterisk and a plus sign on either side of the text, but the asterisk pair must be on the outside of the plus sign pair; otherwise, you’ll get an error.
Another common issue is when inline markup occurs within a single word, like foobar, or if the inline markup abuts some other non-whitespace character on one or more sides (like an em dash), it may render incorrectly like this: foo+bar. The fix for this is to double up the markup. For example: foobar will display as `foo`bar. See #INLINES.
HTML passthroughs sometimes represent the most straightforward way to meet an AsciiDoc formatting challenge (see #passthroughs). For inline markup within code blocks, you should plan on placing the entire code block within a passthrough (see #inline-formatting). What follows are examples of inline passthroughs for formatting regular text in constant-width italic, constant-width bold, and constant-width bold italic, respectively:
pass:[<em><code>foo</code></em>]
pass:[<strong><code>foo</code></strong>]
pass:[<strong><code><em>foo</em></code></strong>]You may also run into difficulties if you want to literally display characters used for Asciidoc markup (e.g., *, +, or _). If there are two or more of the same character in a single line, the Asciidoc parser will read these characters as markup instead of text. To fix this, you can use backslashes to escape these characters. Note that you only need to escape the first character for every set of two. For example:
To display the asterisk characters \*here* and \*here*, escape the first with a backslash.Curly brackets, { and }, may cause rendering problems because they indicate macros in AsciiDoc. If you are having trouble getting curly brackets to render, try escaping them with backslashes like this: \{ and \}
Sidebars
Sidebar markup looks like this:
.Sidebar Title
****
Sidebar text is surrounded by four asterisk characters above and below.
****The appearance of sidebars will vary by theme, but they will look approximately like the following:
Notes, Tips, Warnings, and Cautions
You have the option of using note, tip, and warning 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, or warning, 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 | Tip Title 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 Here’s some text inside a warning. |
Footnotes
To create a footnote, place the footnote macro directly after the text/end punctuation where the note number should appear, with no space between.Otherwise you’ll introduce extra space in the text 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 keyword 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.
Figures and Other Images
Figure markup for figures that will be referenced in the text should include a unique ID attribute (see #XREFS for more info on using cross-references). Please note that a given ID should be unique in the context of an entire book.
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:
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, O’Reilly themes will not give these figures a figure number and the figures cannot be cross-referenced in the body of the text.
Here’s the markup:
image::images/tiger.png["An image of a cartoonish tiger head."]And here’s how it renders:
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"]For some tips on writing good alt text, O’Reilly’s Universal Design for Web Applications is a great resource. In particular, see the section, “Keys to Writing Good Text Alternatives.”
Lists
There are three common types of lists. The following sections provide markup examples of each.
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.This list markup could be rendered like this:
-
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 on its own line 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:
-
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.
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 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 sure that you have the same number of vertical bars for each row.
The table will render with a title and a header row:
| P | Q | P^Q |
|---|---|---|
T | T | T |
T | F | F |
F | T | F |
F | F | F |
Code
Code blocks (or as the AsciiDoctor documentation refers to them, “listing” blocks), are defined using four hyphens above and below the code block content:
[source,java]
----
Hello world!
0 10 20 30 40
1234567890123456789012345678901234567890
----
Which will render like this:
Hello world!
0 10 20 30 40
1234567890123456789012345678901234567890Formal 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:
[source,java]
[[EX1]]
.A code block with a title
====
[source]
----
Hello world!
0 10 20 30 40
1234567890123456789012345678901234567890
----
====
The results:
Hello world!
0 10 20 30 40
1234567890123456789012345678901234567890Inline formatting within code
If you want to use inline formatting in code—in particular, to specify typographical conventions such as bold or italic—you can do so by using an HTML 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 may be rendered like this:
hostname $ date Sun Apr 1 12:34:56 GMT 1984
Angle Brackets in Passthrough Code
If you need to display angle brackets in code that is in a passthrough, make sure to use the entities < (for <) and > (for >) instead of the characters, or you may run into build errors. For example:
++++
<pre data-type="programlisting"><!DOCTYPE HTML>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
The content of the document...
</body>
</html></pre>
++++will render like this:
<!DOCTYPE HTML>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
The content of the document...
</body>
</html>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 using the Pygments short name for the lexer. For example:
[source,java]
----
int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;
----
This will render with colors identifying different syntax elements:
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.
The color scheme for each code language 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]
----
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 ebooks (i.e., you can click on the icon in the code to jump to the explanation, and vice versa).
Here’s the AsciiDoc markup for code callouts:
[source]
----
Roses are red,
Violets are blue.
Some poems rhyme;
This one doesn't.
----
<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)-
Violets actually have a color value of #9933cc.
-
This poem uses the literary device known as a "surprise ending."
To use code callouts with an external AsciiDoc code file, add the callout text items below the code block, like so:
[source]
----
include::code/HelloWorld.java[]
----
<1> This is number one.
<2> This is number two.
Please ensure that the number of callouts in the code block and the number of callout list items match. If they do not (e.g., if the code has three callouts but the list only explains two of them), the toolchain will generate a link pointing to a nonexistent target.
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.
You should not make untitled elements like paragraphs or lists the targets of cross-references. Properly marked-up cross-references without a valid target will be rendered in PDF output as three question marks ("???").
To insert a cross-reference, follow these steps:
-
Note the
idof the element you are referencing. If the element does not have anid, you will need to add one. For the book to be valid, anidmust be unique within the project, have no spaces, and not start with a number. For example, the top line here gives this figure the ID “unique_id”:[[unique_id]] .Figure title image::images/figure.png[] -
Once you have the
id, you can insert a cross-reference to that element elsewhere in the text by enclosing theidin double angle brackets, like so:<<unique_id>>
The Atlas build system will use this id generate HTMLBook cross-reference markup cross-reference (i.e., an <a> element with proper href value) for you. O’Reilly themes will adjust the text in output 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 text generated from the cross-references in PDFs styled with O’Reilly themes.
| 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:
-
See #indexing for details.
-
The result is shown in #unique_id.
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 our implementation of 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 #challenging_inlines for examples of inline passthroughs.
- Block passthroughs
-
You can also pass through a block of HTML by adding four plus signs above and below the block of 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 alt="A Figure" src="images/tiger.png"/> </figure> ++++
Math Support via LaTeX
Atlas supports math equations marked up as LaTeX. For inline LaTeX equations, use the latexmath: macro as follows:
The Pythagorean Theorem is latexmath:[\(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}
++++You could also add a title, like this:
[latexmath]
.The quadratic formula
++++
\begin{equation}
{x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}}
\end{equation}
++++See “Math” for more information.
Controlling Line Breaks
Use an inline passthrough to prevent a line break:
pass:[<span class="keep-together">Don't Break Me</span>]
pass:[<span class="keep-together"><code>foobar</code></span>Please do not use AsciiDoc’s mechanisms for forcing line breaks, as these aren’t supported by Atlas’s toolchain.
Indexing
This section describes how to create an automatically generated index in AsciiDoc. We’ve extended the Asciidoctor index syntax to include ranges, "see"s, and "see also"s.
During production, a freelance indexer will be hired to index your book, so you may not need to use this markup.
Create the index file
To include an index in your book, first create a ix.html file and add this single line of text:
<section data-type="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 ix.html file in the build.
Syntax
Basic index entry:
((("primary index term")))Quotation marks around terms are optional for simple entries:
(((XML, RDF, SPARQL)))However, if you include any attributes (e.g., see, seealso, sortas, or the attributes indicating beginning and end of a range) you must put all terms in quotes:
((("XML", "RDF", "SPARQL", seealso="XQuery")))For anything not mentioned below, please refer to the AsciiDoctor documentation,
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 without a page number that refers the reader only to another entry in the index:
Flash has been supplanted by HTML5.((("Flash", see="HTML5")))You can provide a page reference in combination with a reference to another entry in the index with a seealso, like this:
In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", seealso="RepRap")))The seealso can be applied to a subentry as well:
In addition to the Makerbot, RepRap also allows you to make 3-D stuff
((("Makerbot", "3-D", seealso="RepRap")))To alphabetize an index entry according to a spelling different from that of the term, assign the spelling to the sortas attribute:
Makerbot lets you produce your own 3-D trinkets.((("3-D", sortas="three-d")))