AsciiDoc is a text document format for writing (among other things) books, ebooks, and documentation. It’s similar to wiki markup—if you can write a Wikipedia article, then you’ll have no problem with AsciiDoc. The main advantages of AsciiDoc are that it is easy to use and plays well with O’Reilly’s publishing tools, including Atlas.
|
Note
|
Use the Source, Luke
If you’re viewing this document as a PDF, EPUB, or KF8, you’re seeing the output from the AsciiDoc source, rather than the AsciiDoc markup itself. Since this chapter is intended as an introduction to the markup, it may be helpful to view the source, available at cdn.oreilly.com/atlas_docs.zip. |
There are two ways you can write with AsciiDoc in Atlas:
-
Write directly in the Atlas web interface. Simply click on the "Write" tab in Atlas. Select an existing chapter file to edit, or choose "New File" to create one.
-
Write in a text editor and add it to Atlas. You can add text to Atlas by pasting the text directly into the writing interface or by using git (see [using_git_with_atlas]) to push your local .asciidoc files to the Atlas repository.
Looking for a text editor to use? If you’re on Windows, you could try Notepad++, or any other text editor. If you’re on a Mac, TextEdit, TextMate paired with an AsciiDoc bundle), or TextWrangler, are great choices. Or maybe you prefer old school vi or Emacs. That’s okay, too.
To leave a note to the Production team, please use a passthrough block with the Docbook <remark> element, like this:
++++ <remark>Use a passthrough block like this for notes to production staff</remark> ++++
AsciiDoc does have specific markup for comments (two slash characters, like this: //, followed by the comment text), but they do not get passed to the DocBook output by default. In order to make sure the Production team sees your comments, please use the DocBook passthrough method listed above. (See Passthroughs for more info on DocBook passthroughs.)
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.
If you can’t find what you’re looking for here or if you just need a quick answer, please don’t hesitate to email our support team at toolsreq@oreilly.com.
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 below.
A general understanding of what is going on under the hood of Atlas will help you make the most of the system. When you build your book (as described in [building_and_debugging]), Atlas first converts the AsciiDoc to DocBook XML and then generates the book formats from that DocBook. For each AsciiDoc markup, there is an equivalent DocBook element. As long as the AsciiDoc markup uses the expected syntax, the conversion to DocBook (and then to the book formats) goes smoothly.
If you get a build error, the most likely cause is an AsciiDoc markup error. Atlas provides error message logs to help you troubleshoot and fix syntax errors. Read more about building and debugging in [building_and_debugging].
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.
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
|
Note that 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 DocBook <sect1>). |
Within a chapter, the first and highest heading level uses three equals signs:
=== Top-Level Heading
This heading level should only follow a top-level heading:
==== Second-Level Heading
If you want to group your chapters into parts, navigate to the file that should be the first chapter in that part, and add the part markup above the chapter title. It’s good practice to always include a unique ID string above the part title, like so:
[[unique_part_id]] = Part Title [[unique_chapter_id]] == Chapter Title Chapter text begins here.
To add introductory text to a part, add this partintro markup after the part title, but before the chapter title:
[[unique_part_id]] = Part Title [partintro] -- Insert introductory text here. -- [[unique_chapter_id]] == Chapter Title Chapter text begins here.
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 are treated as prefaces, except they have a title of Foreword. For example:
[preface] == Foreword Foreword text begins here.
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.
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 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.
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
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 ...
For books with multiple contributors, you may want an author name to appear with each chapter. Simply add the following markup above each chapter title:
[au="Author Name"] == Chapter Title
For multiple authors of one chapter, the markup looks like this:
[au="Author Name", au2="Another Author", au3="Last Author"] == Chapter Title
You can also use this same markup for forewords, prefaces, and appendixes. Please note that contributor names in a foreword will render at the end of the foreword, right-aligned, and preceded by an em dash. Foreword author attributions can also include an affiliation. The markup looks like this:
[au="Author Name", auaffil="Editor, Such and Such Journal"]
Here are some standard O’Reilly typographical conventions with explanations of their use:
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. See the previous section Inline Markup.
When all else fails, you can always use passthroughs to embed DocBook markup as is (see Passthroughs). For example, these example passthroughs are rendered as constant-width italic, constant-width bold, and constant-width bold italic, respectively.:
pass:[<replaceable>foo</replaceable>] pass:[<userinput>foo</userinput>] pass:[<userinput><replaceable>foo</replaceable></userinput>]
As an enhancement for finer-tuned semantic distinctions downstream, the Atlas configuration file supports the following variants, via @role attributes:
-
To indicate a filename or path, use: [role="filename"]_/path/to/file.ext_
-
For a book title, use: [role="citetitle"]_This Book Needs No Title_
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 \\}
Sidebar markup looks like this:
.Sidebar Title **** Sidebar text is surrounded by four asterisk characters above and below. ****
Sidebars render like this:
Sidebar text is surrounded by four asterisk characters above and below.
You have the option of using note, tip, warning, and caution elements for supplemental information. Please note that the O’Reilly stylesheets make no visual distinction between the way warning and caution elements render, as well as the way note and tip elements render.
You may also notice that some of the admonitions below have a title. We do support optional titles in admonitions (in most series). 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 [TIP] ==== Here's some text inside a warning. ====
|
Warning
|
Titled Warning
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. |
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 Footnotes section. You should see the content of the note rendering at the bottom of the page.
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.
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:
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:
Figures appear exactly where you place them in the text, which can sometimes create PDF pages with a lot of white space. While it is not generally necessary, you can add an attribute of float="true" so that the text flows around the image:
[[unique_id]] .A Figure [float="true"] image::images/tiger.png[]
To combine a float attribute with alt text, see [combine_alt_and_float] below.
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"]
Please note, to combine the alt-text attribute with a float="true" attribute, use the following markup:
[[unique_id]] .A Figure [float="true"] image::images/tiger.png["An image of a cartoonish tiger head"]
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"]
Or you can use scale as a percentage to limit the width:
image::images/filename.png[scale="75"]
Note that you should not include a percentage sign.
There are three common types of lists. The O’Reilly Stylesheet and Word List has more details about when to use them, but here’s the markup and an example of each.
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.
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.
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.
Atlas table styles vary slightly between series. If your material warrants something other than the default style as shown in An example table, please consult with your editor.
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:
| P | Q | P^Q |
|---|---|---|
T |
T |
T |
T |
F |
F |
F |
T |
F |
F |
F |
F |
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
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:
Hello world! 0 10 20 30 40 1234567890123456789012345678901234567890
In AsciiDoc, there is no built-in mechanism for inline formatting within code.We do support [subs="quotes"] markup in passthrough blocks, but note that this markup can become complicated. Contact toolsreq@oreilly.com with any questions. If you want to use inline formatting—in particular, for standard O’Reilly typographical conventions such as <userinput> (CW+bold) and <replaceable> (CW+italic) or if you want to include line annotations—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 DocBook element <screen>:
++++ <screen> hostname $ <userinput>date</userinput> Sun Apr 1 12:34:56 GMT 1984 </screen> ++++
which renders like this:
And here’s the markup to use a passthrough with the <programlisting> and <lineannotation> DocBook elements:
++++
<programlisting>from __future__ import with_statement # This isn't required in Python 2.6
<lineannotation>Above is a comment in the code, while this is an "annotation"</lineannotation>
with open("<replaceable>hello.txt</replaceable>") as f:
for line in f: <lineannotation>(note regular italic here vs. constant-width in "hello.txt" on line above)</lineannotation>
print line</programlisting>
++++
which renders like this:
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:[2]
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.
Please note the following caveats:
-
The color scheme is consistent across books and cannot be changed at this time.
-
Unless your book is printing in color, the PDF used for print will contain no highlighting.
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 Docbook, 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.txt[] ++++
In the above case, the contents of inline_markup.txt would contain only the DocBook markup. In our example, which might look something like this:
<programlisting>Roses are <replaceable>red</replaceable>, Violets are <replaceable>blue</replaceable>. <lineannotation>This is a line annotation</lineannotation> Some poems rhyme; This one <userinput>doesn't</userinput>.</programlisting>
The results will look like this:
Atlas now supports including “snippets” in your book content so that you can excerpt just a portion of a code listing from an external code file.
|
Note
|
The code snippet functionality is currently in beta. Feedback is welcome. |
Each snippet that you’d like to pull into the book content must be delimited with BEGIN _identifier_ and END _identifier_ comment lines, where _identifier_ is a unique identifier for the given snippet. Here is a sample JavaScript file with one snippet:
alert("This code has a snippet below!");
factorial(3);
// BEGIN FACTORIAL_FUNC
function factorial(number) {
if (number == 0) {
return 1
} else {
return factorial(number - 1) * number
}
}
// END FACTORIAL_FUNCTo include this snippet in an AsciiDoc file, add the following block:
[filename="factorial.js", language="js", identifier="FACTORIAL_FUNC"] snippet~~~~ Put any descriptive text you want here. It will be replaced with the specified code snippet when you build ebook outputs snippet~~~~
When the ebook is generated, the following output will be present in place of the snippet block:
function factorial(number) {
if (number == 0) {
return 1
} else {
return factorial(number - 1) * number
}
}The filename attribute references the external file containing the snippet. Paths to filenames should be relative to the AsciiDoc file to which you’re adding the snippet. So if you’ve got all your book files in the repository root directory, and all your code files in a code directory in the root directory, your filename attribute will look like filename="code/filename.js".
The language attribute is the programming language of the code snippet you’re including. Current supported language values are:
-
clj (clojure)
-
css
-
groovy
-
html
-
java
-
js (javascript)
-
pl (perl)
-
py (python)
-
rb (ruby)
-
scala
-
xml
If you’d like support added for another programming language, please give us feedback.
The identifier attribute references the unique identifier used in your snippet delimiters.
You can nest code snippets within each other like so:
// BEGIN FACTORIAL_FUNC
function factorial(number) {
// BEGIN IF_STATEMENT
if (number == 0) {
return 1
} else {
return factorial(number - 1) * number
}
// END IF_STATEMENT
}
// END FACTORIAL_FUNCWhen snippets that contain nested snippets are referenced for inclusion into book content, the delimiters for nested snippets are removed. For example, if the above FACTORIAL_FUNC snippet is included into the book, the delimiters for the IF_STATEMENT will be stripped out from the code listing.
If you’d like to use AsciiDoc callouts in your external code files, you can comment them out (to ensure the code is runnable), and the comment delimiters will be removed when the snippet is incorporated into the book. For example, the following snippet:
// BEGIN FACTORIAL_FUNC
function factorial(number) {
if (number == 0) { // (1)
return 1
} else { // (2)
return factorial(number - 1) * number
}
}
// END FACTORIAL_FUNCWill be converted to this in the ebook output:
function factorial(number) {
if (number == 0) { (1)
return 1
} else { (2)
return factorial(number - 1) * number
}
}If snippet incorporation fails (e.g., due to a bad filename reference), any text included between the snippet~~~~ delimiters will be used as fallback text.
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).[3]
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:
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.
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:
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.
Standard cross-reference formats shows the standard text generated from the cross-references in PDF builds.
| 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):
-
See Indexing for details.
-
The results is shown in An example figure.
-
Flip ahead to [working_with_github] for a preview.
which were generated from this source:
* See <<indexing>> for details. * The results is shown in <<unique_id>>. * Flip ahead to <<working_with_github>> for a preview.
AsciiDoc 101 makes several references to ``passthroughs.'' You can use a DocBook 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 like this: pass:[passthrough goes here]. See Troubleshooting Inline Markup for examples of inline passthroughs.
- Block passthroughs
-
You can also pass though a block of DocBook XML. Here’s the image markup that we used in AsciiDoc 101, passed through as DocBook:
---- <figure id="unique_id" float="none"> <title>A Figure</title> <mediaobject> <imageobject> <imagedata fileref="images/tiger.png"/> </imageobject> </mediaobject> </figure> ----
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:
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:
If you want to insert a hard page break into your PDF builds, you can do so with this passthrough:
++++ <?hard-pagebreak?> ++++
Please note that adding this page break processing instruction will have no effect on the EPUB and KF8 files.
|
Warning
|
Please do not use AsciiDoc’s mechanisms for forcing page breaks, as these don’t mesh with Atlas’s book building tools. |
Use an inline passthrough to prevent a line break:
pass:[<phrase role='keep-together'>Don'tBreakMe</phrase>]
|
Warning
|
Please do not use AsciiDoc’s mechanisms for forcing line breaks, as these don’t mesh with Atlas’s book building tools. |
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.
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.
See the AsciiDoc source of this documentation for an example index.
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, or contact us if you have index entries with special characters (e.g., quote marks, commas) and need guidance on how to format the markup. |
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")))