asciidoc cheat sheet. GitHub Gist: instantly share code, notes, and snippets. `Inline code`. Inline code. [source,java] /** * @author John Smith */ package ; public. Description. A text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs.
|Published (Last):||1 August 2017|
|PDF File Size:||10.68 Mb|
|ePub File Size:||6.55 Mb|
|Price:||Free* [*Free Regsitration Required]|
Atlas supports writing in AsciiDoca text document format for writing among other things books, ebooks, and documentation. AsciiDoc files in Atlas can be edited using the Code Editor.
This section illustrates some of the most common elements used in writing technical documentation. 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:. To learn how to add inline markup such as italics to your text see the Inline Markup section.
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:. 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. The levels described in the AsciiDoc User Guide can be confusing: If you want to group your chapters into parts, you can do so by creating a new asciidoc file for example, part1.
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. 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:.
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:. The markup for an Afterword is similar to the preface markup, but it has an additional role attribute with a value of “afterword”.
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 pages render on their own page at the beginning of the book, before the table of contents.
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 glossarythis time in single brackets. Each glossary entry should consist of one glossary term, followed by two colons and a space, then the glossary definition. 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 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:. 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.
Italic text indicates new terms, URLs, saciidoc addresses, filenames, and file extensions. The AsciiDoc markup is one underscore character on either side of the text shdet 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: 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: 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: 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. 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: 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. 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: For hyperlinks to external sources, just add cueat 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 ccheat.
In print versions, it will appear in the text, followed by the actual URL in parenthesis. 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.
AsciiDoc Home Page
Tip Title line in the markup below. This is how warnings render. Warnings can be used for including supplemental information in your text. Including asciidocc warning title is optional. This ascidioc 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. Footnotes at the end of a sentence belong eheet the period:.
For an example of aeciidoc footnote rendering, see the first paragraph in this section. You should see the content saciidoc the note rendering at the bottom of the page. The text of the quote itself should appear immediately below, with four underscore characters above and below 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.
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. To improve asciiddoc in your zheet 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:. While it should not be necessary in most circumstances, you can control the size of an saciidoc in the PDF output by adding an absolute value of width or height, like so:. Note that the final item in the list has multiple paragraphs. Note that a single vertical bar character is used to separate each box in the table. 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. Here is the markup if you want to add syntax highlighting to a formal code block—note the placement of [source] is the same:. Pygments supports a wide variety of languages that can cheta 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.
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 formattingor you can include an external file marked up with valid XHTML, which can contain inline markup. Callouts will work with either method.
Writing in AsciiDoc
To include an external code file that is text-only no inline markup besides calloutsuse the include:: For info about using callouts with your external AsciiDoc chsat file, see Code callouts.
To include an external file that contains inline markup e. In our example, which might look something like this:. Code cheay 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.
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:.
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.
Note the id of the element you are referencing. If the element does not have an idyou will need to add one. For the book to be valid, id s must be unique across the entire book, have no spaces, and not start with a number.
For example, aheet figure id looks like this:. Once you have the idyou can insert a cross-reference to that element elsewhere in the text by enclosing the id in double angle brackets, like asciidocc.
AsciiDoc supports two types of passthroughs:. For inlines, you can indicate a passthrough at any time by adding this passthrough markup within the text paragraph:. See Troubleshooting Inline Markup for examples of inline passthroughs. Atlas supports math equations set as LaTeX. For inline LaTeX equations, use the latexmath: This section describes how to create an automatically generated index in AsciiDoc.