From d879804d47f13c92e8e33209f279dcf538f6904f Mon Sep 17 00:00:00 2001 From: test2 Date: Thu, 24 Oct 2019 00:32:33 +0300 Subject: [PATCH] ref --- asciidoc/AsciiDocSyntaxQuickReference.adoc | 6666 -------------------- 1 file changed, 6666 deletions(-) diff --git a/asciidoc/AsciiDocSyntaxQuickReference.adoc b/asciidoc/AsciiDocSyntaxQuickReference.adoc index e81f9a9..2b55c90 100644 --- a/asciidoc/AsciiDocSyntaxQuickReference.adoc +++ b/asciidoc/AsciiDocSyntaxQuickReference.adoc @@ -1285,6672 +1285,6 @@ include::{includedir}/ex-hr.adoc[tag=md] To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. -= AsciiDoc Syntax Quick Reference -Dan Allen; Sarah White -v1.0.4, 2014-08-08 -:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. -:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet -:page-description: {description} -:page-keywords: {keywords} -:page-layout: docs -:page-javascripts: [view-result] -:imagesdir: ../images -:includedir: _includes -:experimental: -:table-caption!: -:example-caption!: -:figure-caption!: -ifndef::env-site[] -:idprefix: -:idseparator: - -:toc: macro -endif::[] -// URLs -:docs: link:../ -ifdef::env-github[:docs: https://asciidoctor.org/docs/] -:user: {docs}user-manual/ -ifdef::env-browser[] -:docs: link:index.adoc -:user: link:user-manual.adoc -endif::[] -:uri-fontawesome: https://fontawesome.com/v4.7.0/ -:uri-icon-in: {user}#inline-icons -:uri-icon-attrs: {user}#size-rotate-and-flip -:uri-video: {user}#video -:uri-checklist: {user}#checklist -:uri-marker: {user}#custom-markers -:uri-list-num: {user}#numbering-styles -:uri-imagesdir: {user}#setting-the-location-of-images -:uri-image-attrs: {user}#putting-images-in-their-place -:uri-toc: {user}#user-toc -:uri-para: {user}#paragraph -:uri-literal: {user}#literal-text-and-blocks -:uri-admon: {user}#admonition -:uri-bold: {user}#bold-and-italic -:uri-quote: {user}#curved -:uri-sub: {user}#subscript-and-superscript -:uri-mono: {user}#mono -:uri-css: {user}#custom-styling-with-attributes -:uri-pass: {user}#pass-macros -:uri-mailinglist: http://discuss.asciidoctor.org -:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references -:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs - -//// -Syntax to cover: -- preface -- index terms -- built-in attributes (such as {author}, {revision}, etc) -- start=n for ordered lists -- horizontal description list -- anchor for any block element -- block metadata (missing example of normal attributes) -- command line reference? perhaps another doc? yes - -PDF TODO: -- add license on title page (legalnotice tag) -- table cell bg -- show example of section levels -- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) -- style sidebar block -//// - -ifdef::basebackend-docbook[] -[preface] -== About -endif::basebackend-docbook[] - -AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. -{description} - -[NOTE] -==== -These examples focus on the output generated by the HTML backend. -AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. -==== - -toc::[] - -== Paragraphs - -.Normal ----- -include::{includedir}/ex-text.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-para] -==== - -.Literal ----- -include::{includedir}/ex-literal.adoc[tag=b-imp] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp] -==== - -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-admon.adoc[tag=b-para] -==== - -NOTE: You can also create <>. - -.Lead paragraph ----- -include::{includedir}/ex-text.adoc[tag=b-lead] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-lead] -==== - -NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. - -.More Paragraph, Admonition and Literal Block Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-para}[Paragraphs] -* {uri-literal}[Literal Text and Blocks] -* {uri-admon}[Admonitions] -**** - -== Formatted Text - -.Bold, Italic, and Monospace ----- -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] -==== - -.Monospace vs codespan ----- -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] -==== - -NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. -Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. -See the <> for details. - -.Marks and Custom Styling ----- -include::{includedir}/ex-text.adoc[tag=css-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=css-all] -==== - -.Superscript and Subscript ----- -include::{includedir}/ex-text.adoc[tag=b-sub-sup] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-sub-sup] -==== - -.Curved Quotation Marks and Apostrophes (Smart Quotes) ----- -include::{includedir}/ex-text.adoc[tag=b-c-quote] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-c-quote] -==== - -.More Text Formatting Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-bold}[Bold and Italic Formatting] -* {uri-quote}[Quotation Marks and Apostrophes] -* {uri-sub}[Subscript and Superscript] -* {uri-mono}[Monospace Formatting] -* {uri-css}[Custom Styling with Attributes] -* {uri-pass}[Passthrough Macros] -**** - -== Document Header - -IMPORTANT: A header is optional. - -CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. - -.Title only ----- -include::{includedir}/ex-header-title.adoc[tag=b-base] ----- - -.Title and author line ----- -include::{includedir}/ex-author.adoc[tag=b-base] ----- - -TIP: Asciidoctor allows multiple authors in the author line. -Use the semi-colon character to separate each author. - -.Title, author line and revision line ----- -include::{includedir}/ex-rev.adoc[tag=b-base] ----- - -IMPORTANT: You cannot have a revision line without an author line. - -.Document header with attributes ----- -include::{includedir}/ex-header-attr.adoc[tag=b-base] ----- - -[#section-titles] -== Section Titles (Headings) - -.Article doctype ----- -include::{includedir}/ex-section.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-base] -==== - -WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. - -NOTE: The number of equal signs matches the heading level in the HTML output. -For example, _Section Level 1_ becomes an `

` heading. - -.Book doctype ----- -include::{includedir}/ex-section.adoc[tag=book] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-book] -==== - -//// -IMPORTANT: There are two other ways to define a section title. -_Their omission is intentional_. -They both require more markup and are therefore unnecessary. -The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. -The reader never sees the extra markup, so why type it? -*Be frugal!* -//// - -.Explicit id ----- -[#primitives-nulls] -== Primitive types and null values ----- - -.Section anchors and links (Asciidoctor only) - -`sectanchors`:: -When this document attribute is set, a section icon anchor appears in front of the section title. - -`sectlinks`:: -When this document attribute is set, the section titles become self-links. -This enables a reader to bookmark the section. - -NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. - -== Include Files - -.Document parts ----- -include::{includedir}/ex-include.adoc[tag=base] ----- - -CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. -Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. - -.Include content from a URI ----- -include::{includedir}/ex-include.adoc[tag=uri] ----- - -NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. -Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. - -== Breaks - -.Hard line break ----- -include::{includedir}/ex-text.adoc[tag=hb-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=hb-all] -==== - -.Thematic break (aka horizontal rule) ----- -include::{includedir}/ex-hr.adoc[tag=in-between] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=in-between] -==== - -.Page break ----- -<<< ----- - -== Lists - -.Unordered, basic ----- -include::{includedir}/ex-ulist.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base] -==== - -.Unordered, basic (alt) ----- -include::{includedir}/ex-ulist.adoc[tag=base-alt] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base-alt] -==== - -NOTE: A blank line is required before and after a list to separated it from other blocks. - -TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. -The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. - -.Unordered, max nesting ----- -include::{includedir}/ex-ulist.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=max] -==== - -TIP: The unordered list marker can be changed using {uri-marker}[block styles]. - -.Ordered, basic ----- -include::{includedir}/ex-o-list.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=b-base] -==== - -NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. - -.Ordered, nested ----- -include::{includedir}/ex-o-list.adoc[tag=nest] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=nest] -==== - -.Ordered, max nesting ----- -include::{includedir}/ex-o-list.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=max] -==== - -TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. - -.Checklist ----- -include::{includedir}/ex-ulist.adoc[tag=check] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=check] -==== - -TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. - -.Description, single-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base] -==== - -.Description, multi-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] -==== - -.Q&A ----- -include::{includedir}/ex-dlist.adoc[tag=qa] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=qa] -==== - -.Mixed ----- -include::{includedir}/ex-dlist.adoc[tag=3-mix] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=3-mix] -==== - -TIP: Lists can be indented. -Leading whitespace is not significant. - -.Complex content in outline lists ----- -include::{includedir}/ex-ulist.adoc[tag=b-complex] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=b-complex] -==== - -== Links - -.External ----- -include::{includedir}/ex-url.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-base] -==== - -.With spaces and special characters ----- -include::{includedir}/ex-url.adoc[tag=b-spaces] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-spaces] -==== - -.Windows path ----- -include::{includedir}/ex-url.adoc[tag=b-windows] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-windows] -==== - -.Relative ----- -link:index.html[Docs] ----- - -[.result] -==== -link:index.html[Docs] -==== - -.Email and IRC ----- -include::{includedir}/ex-url.adoc[tag=b-scheme] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-scheme] -==== - -.Link with attributes (Asciidoctor only) ----- -include::{includedir}/ex-url.adoc[tag=b-linkattrs] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-linkattrs] -==== - -NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. -To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. -Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. -When attribute parsing is enabled, you must quote the link text if it contains a comma. - -.Inline anchors ----- -include::{includedir}/ex-xref.adoc[tag=anchor] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=anchor] -==== - -.Internal cross references ----- -include::{includedir}/ex-xref.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=b-base] -==== - -.Inter-document cross references (Asciidoctor only) ----- -include::{includedir}/ex-xref.adoc[tag=b-inter] ----- - -== Images - -Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. -You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. - -The `imagesdir` attribute can be an absolute path, relative path, or base URL. -When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. - -.Block ----- -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] -==== - -.Inline ----- -include::{includedir}/ex-image.adoc[tag=in] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in] -==== - -IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. -(All macros follow this pattern). -You use an inline image when you need to place the image in a line of text. -Otherwise, you should prefer the block form. - -.Inline image with positioning role ----- -include::{includedir}/ex-image.adoc[tag=in-role] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in-role] -==== - -TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. - -.Embedded ----- -include::{includedir}/ex-image.adoc[tag=data] ----- - -NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. - -TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. - -== Videos - -.Block ----- -include::{includedir}/ex-video.adoc[tag=base] - -include::{includedir}/ex-video.adoc[tag=attr] ----- - -.Embedded Youtube video ----- -include::{includedir}/ex-video.adoc[tag=you] ----- - -.Embedded Vimeo video ----- -include::{includedir}/ex-video.adoc[tag=vim] ----- - -TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. - -== Source Code - -.Inline (monospace only) ----- -include::{includedir}/ex-text.adoc[tag=b-mono-code] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-mono-code] -==== - -.Inline (literal) ----- -include::{includedir}/ex-pass.adoc[tag=backtick-plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=backtick-plus] -==== - -.Literal line ----- -include::{includedir}/ex-literal.adoc[tag=b-imp-code] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp-code] -==== - -.Literal block ----- -include::{includedir}/ex-literal.adoc[tag=b-block] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-block] -==== - -[listing] -.Listing block with title, no syntax highlighting -.... -include::{includedir}/ex-listing.adoc[tag=b-base] -.... - -[.result] -==== -include::{includedir}/ex-listing.adoc[tag=b-base] -==== - -[listing] -.Code block with title and syntax highlighting -.... -include::{includedir}/ex-src.adoc[tag=src-base] -.... - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-base] -==== - -[listing,subs=specialchars] -.Code block with callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-src] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-src] -==== - -[listing,subs=specialchars] -.Code block with non-selectable callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -==== - -[listing,subs=specialchars] -.XML code block with a non-selectable callout -.... -include::{includedir}/ex-callout.adoc[tag=source-xml] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=source-xml] -==== - -[listing] -.Code block sourced from file -.... -include::{includedir}/ex-src.adoc[tag=src-inc] -.... - -[listing] -.Code block sourced from file relative to source directory -.... -include::{includedir}/ex-src.adoc[tag=rel] -.... - -[listing] -.Strip leading indentation from source -.... -include::{includedir}/ex-src.adoc[tag=ind] -.... - -[NOTE] -==== -* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). -* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. -==== - -.Code block without delimiters (no blank lines) ----- -include::{includedir}/ex-src.adoc[tag=src-para] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-para] -==== - -[IMPORTANT] -.Enabling the syntax highlighter -==== -Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. - - :source-highlighter: pygments - -The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. -==== - -== More Delimited Blocks - -.Sidebar ----- -include::{includedir}/ex-sidebar.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-sidebar.adoc[tag=base] -==== - -NOTE: Any block can have a title, positioned above the block. -A block title is a line of text that starts with a dot. -The dot cannot be followed by a space. - -.Example ----- -include::{includedir}/ex-example.adoc[tag=base] ----- - -[example.result] --- -include::{includedir}/ex-example.adoc[tag=base] --- - -[#admon-bl] -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-bl] ----- - -[.result] -===== -include::{includedir}/ex-admon.adoc[tag=b-bl] -===== - -[TIP] -.Admonition and callout icons -==== -Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. - -To use this feature, set the value of the `icons` document attribute to `font`. -Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. - -Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. -==== - -.Blockquote ----- -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] -==== - -.Abbreviated blockquote (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=abbr] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=abbr] -==== - -.Air quotes: the best thing since fenced code blocks (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=air] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=air] -==== - -.Passthrough ----- -include::{includedir}/ex-pass.adoc[tag=b-bl] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-bl] -==== - -.Open ----- -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] ----- - -[.result] -==== -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] -==== - -[listing] -.Custom substitutions -.... -include::{includedir}/ex-listing.adoc[tag=subs] -.... - -[.result] -==== -// the attribute value is hard-coded in this result since the example depends -// on a hypothetical document attribute -include::{includedir}/ex-listing.adoc[tag=subs-out] -==== - -== Block Id, Role and Options - -.Traditional (longhand) markup method for assigning block id and role ----- -[[goals]] -[role="incremental"] -* Goal 1 -* Goal 2 ----- - -.Shorthand markup method for assigning block id and role (Asciidoctor only) ----- -[#goals.incremental] -* Goal 1 -* Goal 2 ----- - -[TIP] -==== -* To specify multiple roles using the shorthand syntax, separate them by dots. -* The order of `id` and `role` values in the shorthand syntax does not matter. -==== - -.Traditional (longhand) markup method for assigning quoted text anchor (id) and role ----- -[[free_the_world]][big goal]_free the world_ ----- - -.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) ----- -[#free_the_world.big.goal]_free the world_ ----- - -.Role assigned to text enclosed in backticks ----- -[.rolename]`monospace text` ----- - -.Traditional (longhand) markup method for assigning block options ----- -[options="header,footer,autowidth"] -|=== -|Cell A |Cell B -|=== ----- - -.Shorthand markup method for assigning block options (Asciidoctor only) ----- -[%header%footer%autowidth] -|=== -|Cell A |Cell B -|=== ----- - -== Comments - -.Line ----- -include::{includedir}/ex-comment.adoc[tag=line] ----- - -TIP: Single-line comments can be used to divide elements, such as two adjacent lists. - -.Block ----- -include::{includedir}/ex-comment.adoc[tag=bl] ----- - -== Tables - -.Table with a title, three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-base-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-base-h] -==== -<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. -<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. - -.Table with two columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-h] -==== -<1> The `+*+` in the `cols` attribute is the repeat operator. -It means repeat the column specification across the remaining of columns. -In this case, we are repeating the default formatting across 2 columns. -When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. - -.Table with three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-indv-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-indv] -==== -<1> In this example, the `cols` attribute has two functions. -It specifies that this table has three columns, and it sets their relative widths. - -.Table with column containing AsciiDoc content ----- -include::{includedir}/ex-table.adoc[tag=b-col-a] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-a] -==== - -.Table from CSV data ----- -include::{includedir}/ex-table-data.adoc[tag=csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=csv] -==== - -.Table from CSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-csv] -==== - -.Table from CSV data in file ----- -include::{includedir}/ex-table-data.adoc[tag=i-csv] ----- - -.Table from DSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-dsv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-dsv] -==== - -.Table with formatted, aligned and merged cells ----- -include::{includedir}/ex-table-cell.adoc[tag=b-spec] ----- - -[.result] -==== -include::{includedir}/ex-table-cell.adoc[tag=b-spec] -==== - -== UI Macros - -IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. - -.Keyboard shortcuts (inline kbd macro) ----- -include::{includedir}/ex-ui.adoc[tag=key] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=key] -==== - -.Menu selections (inline menu macro) ----- -include::{includedir}/ex-ui.adoc[tag=menu] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=menu] -==== - -.Buttons (inline btn macro) ----- -include::{includedir}/ex-ui.adoc[tag=button] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=button] -==== - -== Attributes and Substitutions - -.Attribute declaration and usage ----- -include::{includedir}/ex-header-attr.adoc[tag=b-attr] ----- - -[.result] -==== -// I have to use a nested doc hack here, otherwise the attributes won't resolve -[.unstyled] -|=== -a| -include::{includedir}/ex-header-attr.adoc[tag=b-attr] -|=== -==== - -.Attribute assignment precedence (highest to lowest) -- Attribute passed to the API or CLI that does not end in `@` -- Attribute defined in the document -- Attribute passed to the API or CLI that ends in `@` -- Intrinsic attribute value (default values) - -TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. - -// Table of predefined attributes for character replacements -include::{includedir}/attrs-charref.adoc[tag=table] - -// Table of environment attributes -include::{includedir}/attrs-env.adoc[tag=table] - -.Named substitutions -include::{includedir}/subs-apply.adoc[tag=group] - -.Counter attributes ----- -include::{includedir}/ex-counter.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-counter.adoc[tag=base] -==== - -== Text Replacement - -// Table of text replacements performed during replacements substitution -include::{includedir}/subs-symbol-repl.adoc[] - -TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. - -== Escaping Text - -.Backslash ----- -include::{includedir}/ex-subs.adoc[tag=b-slash] ----- - -[.result] -==== -include::{includedir}/ex-subs.adoc[tag=b-slash] -==== - -.Passthrough ("`plus for passthrough`") ----- -include::{includedir}/ex-pass.adoc[tag=plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=plus] -==== - -//// -.Double dollar ----- -include::{includedir}/ex-pass.adoc[tag=b-dollar] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-dollar] -==== -//// - -.Raw (triple plus and inline pass macro) ----- -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] -==== - -//// -.Backticks ----- -include::{includedir}/ex-pass.adoc[tag=b-tick] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-tick] -==== -//// - -== Table of Contents (ToC) - -.Document with ToC ----- -include::{includedir}/ex-toc.adoc[tag=base] ----- - -.Document with ToC positioned on the right ----- -include::{includedir}/ex-toc.adoc[tag=pos] ----- - -TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. - -== Bibliography - -.Bibliography with inbound references ----- -include::{includedir}/ex-biblio.adoc[tag=base] ----- - -[.result] -==== -|=== -a| -include::{includedir}/ex-biblio.adoc[tag=base] -|=== -==== - -[#section-footnotes] -== Footnotes - -.Normal and reusable footnotes ----- -include::{includedir}/ex-footnote.adoc[tag=base] ----- - -[.result] -==== -[.unstyled] -|=== -a| -include::{includedir}/ex-footnote.adoc[tag=base] -|=== -==== - -[#markdown-compatibility] -== Markdown Compatibility - -Markdown compatible syntax is only available when using Asciidoctor. - -.Markdown-style headings ----- -include::{includedir}/ex-section.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-md] -==== - -.Fenced code block with syntax highlighting ----- -include::{includedir}/ex-src.adoc[tag=fence] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=fence] -==== - -.Markdown-style blockquote ----- -include::{includedir}/ex-quote.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md] -==== - -.Markdown-style blockquote with block content ----- -include::{includedir}/ex-quote.adoc[tag=md-alt] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md-alt] -==== - -.Markdown-style horizontal rules ----- -include::{includedir}/ex-hr.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=md] -==== - -== User Manual and Help - -To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. -Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. -= AsciiDoc Syntax Quick Reference -Dan Allen; Sarah White -v1.0.4, 2014-08-08 -:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. -:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet -:page-description: {description} -:page-keywords: {keywords} -:page-layout: docs -:page-javascripts: [view-result] -:imagesdir: ../images -:includedir: _includes -:experimental: -:table-caption!: -:example-caption!: -:figure-caption!: -ifndef::env-site[] -:idprefix: -:idseparator: - -:toc: macro -endif::[] -// URLs -:docs: link:../ -ifdef::env-github[:docs: https://asciidoctor.org/docs/] -:user: {docs}user-manual/ -ifdef::env-browser[] -:docs: link:index.adoc -:user: link:user-manual.adoc -endif::[] -:uri-fontawesome: https://fontawesome.com/v4.7.0/ -:uri-icon-in: {user}#inline-icons -:uri-icon-attrs: {user}#size-rotate-and-flip -:uri-video: {user}#video -:uri-checklist: {user}#checklist -:uri-marker: {user}#custom-markers -:uri-list-num: {user}#numbering-styles -:uri-imagesdir: {user}#setting-the-location-of-images -:uri-image-attrs: {user}#putting-images-in-their-place -:uri-toc: {user}#user-toc -:uri-para: {user}#paragraph -:uri-literal: {user}#literal-text-and-blocks -:uri-admon: {user}#admonition -:uri-bold: {user}#bold-and-italic -:uri-quote: {user}#curved -:uri-sub: {user}#subscript-and-superscript -:uri-mono: {user}#mono -:uri-css: {user}#custom-styling-with-attributes -:uri-pass: {user}#pass-macros -:uri-mailinglist: http://discuss.asciidoctor.org -:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references -:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs - -//// -Syntax to cover: -- preface -- index terms -- built-in attributes (such as {author}, {revision}, etc) -- start=n for ordered lists -- horizontal description list -- anchor for any block element -- block metadata (missing example of normal attributes) -- command line reference? perhaps another doc? yes - -PDF TODO: -- add license on title page (legalnotice tag) -- table cell bg -- show example of section levels -- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) -- style sidebar block -//// - -ifdef::basebackend-docbook[] -[preface] -== About -endif::basebackend-docbook[] - -AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. -{description} - -[NOTE] -==== -These examples focus on the output generated by the HTML backend. -AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. -==== - -toc::[] - -== Paragraphs - -.Normal ----- -include::{includedir}/ex-text.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-para] -==== - -.Literal ----- -include::{includedir}/ex-literal.adoc[tag=b-imp] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp] -==== - -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-admon.adoc[tag=b-para] -==== - -NOTE: You can also create <>. - -.Lead paragraph ----- -include::{includedir}/ex-text.adoc[tag=b-lead] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-lead] -==== - -NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. - -.More Paragraph, Admonition and Literal Block Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-para}[Paragraphs] -* {uri-literal}[Literal Text and Blocks] -* {uri-admon}[Admonitions] -**** - -== Formatted Text - -.Bold, Italic, and Monospace ----- -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] -==== - -.Monospace vs codespan ----- -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] -==== - -NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. -Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. -See the <> for details. - -.Marks and Custom Styling ----- -include::{includedir}/ex-text.adoc[tag=css-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=css-all] -==== - -.Superscript and Subscript ----- -include::{includedir}/ex-text.adoc[tag=b-sub-sup] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-sub-sup] -==== - -.Curved Quotation Marks and Apostrophes (Smart Quotes) ----- -include::{includedir}/ex-text.adoc[tag=b-c-quote] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-c-quote] -==== - -.More Text Formatting Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-bold}[Bold and Italic Formatting] -* {uri-quote}[Quotation Marks and Apostrophes] -* {uri-sub}[Subscript and Superscript] -* {uri-mono}[Monospace Formatting] -* {uri-css}[Custom Styling with Attributes] -* {uri-pass}[Passthrough Macros] -**** - -== Document Header - -IMPORTANT: A header is optional. - -CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. - -.Title only ----- -include::{includedir}/ex-header-title.adoc[tag=b-base] ----- - -.Title and author line ----- -include::{includedir}/ex-author.adoc[tag=b-base] ----- - -TIP: Asciidoctor allows multiple authors in the author line. -Use the semi-colon character to separate each author. - -.Title, author line and revision line ----- -include::{includedir}/ex-rev.adoc[tag=b-base] ----- - -IMPORTANT: You cannot have a revision line without an author line. - -.Document header with attributes ----- -include::{includedir}/ex-header-attr.adoc[tag=b-base] ----- - -[#section-titles] -== Section Titles (Headings) - -.Article doctype ----- -include::{includedir}/ex-section.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-base] -==== - -WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. - -NOTE: The number of equal signs matches the heading level in the HTML output. -For example, _Section Level 1_ becomes an `

` heading. - -.Book doctype ----- -include::{includedir}/ex-section.adoc[tag=book] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-book] -==== - -//// -IMPORTANT: There are two other ways to define a section title. -_Their omission is intentional_. -They both require more markup and are therefore unnecessary. -The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. -The reader never sees the extra markup, so why type it? -*Be frugal!* -//// - -.Explicit id ----- -[#primitives-nulls] -== Primitive types and null values ----- - -.Section anchors and links (Asciidoctor only) - -`sectanchors`:: -When this document attribute is set, a section icon anchor appears in front of the section title. - -`sectlinks`:: -When this document attribute is set, the section titles become self-links. -This enables a reader to bookmark the section. - -NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. - -== Include Files - -.Document parts ----- -include::{includedir}/ex-include.adoc[tag=base] ----- - -CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. -Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. - -.Include content from a URI ----- -include::{includedir}/ex-include.adoc[tag=uri] ----- - -NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. -Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. - -== Breaks - -.Hard line break ----- -include::{includedir}/ex-text.adoc[tag=hb-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=hb-all] -==== - -.Thematic break (aka horizontal rule) ----- -include::{includedir}/ex-hr.adoc[tag=in-between] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=in-between] -==== - -.Page break ----- -<<< ----- - -== Lists - -.Unordered, basic ----- -include::{includedir}/ex-ulist.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base] -==== - -.Unordered, basic (alt) ----- -include::{includedir}/ex-ulist.adoc[tag=base-alt] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base-alt] -==== - -NOTE: A blank line is required before and after a list to separated it from other blocks. - -TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. -The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. - -.Unordered, max nesting ----- -include::{includedir}/ex-ulist.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=max] -==== - -TIP: The unordered list marker can be changed using {uri-marker}[block styles]. - -.Ordered, basic ----- -include::{includedir}/ex-o-list.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=b-base] -==== - -NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. - -.Ordered, nested ----- -include::{includedir}/ex-o-list.adoc[tag=nest] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=nest] -==== - -.Ordered, max nesting ----- -include::{includedir}/ex-o-list.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=max] -==== - -TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. - -.Checklist ----- -include::{includedir}/ex-ulist.adoc[tag=check] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=check] -==== - -TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. - -.Description, single-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base] -==== - -.Description, multi-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] -==== - -.Q&A ----- -include::{includedir}/ex-dlist.adoc[tag=qa] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=qa] -==== - -.Mixed ----- -include::{includedir}/ex-dlist.adoc[tag=3-mix] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=3-mix] -==== - -TIP: Lists can be indented. -Leading whitespace is not significant. - -.Complex content in outline lists ----- -include::{includedir}/ex-ulist.adoc[tag=b-complex] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=b-complex] -==== - -== Links - -.External ----- -include::{includedir}/ex-url.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-base] -==== - -.With spaces and special characters ----- -include::{includedir}/ex-url.adoc[tag=b-spaces] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-spaces] -==== - -.Windows path ----- -include::{includedir}/ex-url.adoc[tag=b-windows] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-windows] -==== - -.Relative ----- -link:index.html[Docs] ----- - -[.result] -==== -link:index.html[Docs] -==== - -.Email and IRC ----- -include::{includedir}/ex-url.adoc[tag=b-scheme] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-scheme] -==== - -.Link with attributes (Asciidoctor only) ----- -include::{includedir}/ex-url.adoc[tag=b-linkattrs] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-linkattrs] -==== - -NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. -To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. -Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. -When attribute parsing is enabled, you must quote the link text if it contains a comma. - -.Inline anchors ----- -include::{includedir}/ex-xref.adoc[tag=anchor] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=anchor] -==== - -.Internal cross references ----- -include::{includedir}/ex-xref.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=b-base] -==== - -.Inter-document cross references (Asciidoctor only) ----- -include::{includedir}/ex-xref.adoc[tag=b-inter] ----- - -== Images - -Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. -You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. - -The `imagesdir` attribute can be an absolute path, relative path, or base URL. -When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. - -.Block ----- -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] -==== - -.Inline ----- -include::{includedir}/ex-image.adoc[tag=in] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in] -==== - -IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. -(All macros follow this pattern). -You use an inline image when you need to place the image in a line of text. -Otherwise, you should prefer the block form. - -.Inline image with positioning role ----- -include::{includedir}/ex-image.adoc[tag=in-role] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in-role] -==== - -TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. - -.Embedded ----- -include::{includedir}/ex-image.adoc[tag=data] ----- - -NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. - -TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. - -== Videos - -.Block ----- -include::{includedir}/ex-video.adoc[tag=base] - -include::{includedir}/ex-video.adoc[tag=attr] ----- - -.Embedded Youtube video ----- -include::{includedir}/ex-video.adoc[tag=you] ----- - -.Embedded Vimeo video ----- -include::{includedir}/ex-video.adoc[tag=vim] ----- - -TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. - -== Source Code - -.Inline (monospace only) ----- -include::{includedir}/ex-text.adoc[tag=b-mono-code] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-mono-code] -==== - -.Inline (literal) ----- -include::{includedir}/ex-pass.adoc[tag=backtick-plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=backtick-plus] -==== - -.Literal line ----- -include::{includedir}/ex-literal.adoc[tag=b-imp-code] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp-code] -==== - -.Literal block ----- -include::{includedir}/ex-literal.adoc[tag=b-block] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-block] -==== - -[listing] -.Listing block with title, no syntax highlighting -.... -include::{includedir}/ex-listing.adoc[tag=b-base] -.... - -[.result] -==== -include::{includedir}/ex-listing.adoc[tag=b-base] -==== - -[listing] -.Code block with title and syntax highlighting -.... -include::{includedir}/ex-src.adoc[tag=src-base] -.... - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-base] -==== - -[listing,subs=specialchars] -.Code block with callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-src] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-src] -==== - -[listing,subs=specialchars] -.Code block with non-selectable callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -==== - -[listing,subs=specialchars] -.XML code block with a non-selectable callout -.... -include::{includedir}/ex-callout.adoc[tag=source-xml] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=source-xml] -==== - -[listing] -.Code block sourced from file -.... -include::{includedir}/ex-src.adoc[tag=src-inc] -.... - -[listing] -.Code block sourced from file relative to source directory -.... -include::{includedir}/ex-src.adoc[tag=rel] -.... - -[listing] -.Strip leading indentation from source -.... -include::{includedir}/ex-src.adoc[tag=ind] -.... - -[NOTE] -==== -* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). -* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. -==== - -.Code block without delimiters (no blank lines) ----- -include::{includedir}/ex-src.adoc[tag=src-para] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-para] -==== - -[IMPORTANT] -.Enabling the syntax highlighter -==== -Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. - - :source-highlighter: pygments - -The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. -==== - -== More Delimited Blocks - -.Sidebar ----- -include::{includedir}/ex-sidebar.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-sidebar.adoc[tag=base] -==== - -NOTE: Any block can have a title, positioned above the block. -A block title is a line of text that starts with a dot. -The dot cannot be followed by a space. - -.Example ----- -include::{includedir}/ex-example.adoc[tag=base] ----- - -[example.result] --- -include::{includedir}/ex-example.adoc[tag=base] --- - -[#admon-bl] -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-bl] ----- - -[.result] -===== -include::{includedir}/ex-admon.adoc[tag=b-bl] -===== - -[TIP] -.Admonition and callout icons -==== -Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. - -To use this feature, set the value of the `icons` document attribute to `font`. -Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. - -Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. -==== - -.Blockquote ----- -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] -==== - -.Abbreviated blockquote (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=abbr] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=abbr] -==== - -.Air quotes: the best thing since fenced code blocks (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=air] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=air] -==== - -.Passthrough ----- -include::{includedir}/ex-pass.adoc[tag=b-bl] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-bl] -==== - -.Open ----- -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] ----- - -[.result] -==== -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] -==== - -[listing] -.Custom substitutions -.... -include::{includedir}/ex-listing.adoc[tag=subs] -.... - -[.result] -==== -// the attribute value is hard-coded in this result since the example depends -// on a hypothetical document attribute -include::{includedir}/ex-listing.adoc[tag=subs-out] -==== - -== Block Id, Role and Options - -.Traditional (longhand) markup method for assigning block id and role ----- -[[goals]] -[role="incremental"] -* Goal 1 -* Goal 2 ----- - -.Shorthand markup method for assigning block id and role (Asciidoctor only) ----- -[#goals.incremental] -* Goal 1 -* Goal 2 ----- - -[TIP] -==== -* To specify multiple roles using the shorthand syntax, separate them by dots. -* The order of `id` and `role` values in the shorthand syntax does not matter. -==== - -.Traditional (longhand) markup method for assigning quoted text anchor (id) and role ----- -[[free_the_world]][big goal]_free the world_ ----- - -.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) ----- -[#free_the_world.big.goal]_free the world_ ----- - -.Role assigned to text enclosed in backticks ----- -[.rolename]`monospace text` ----- - -.Traditional (longhand) markup method for assigning block options ----- -[options="header,footer,autowidth"] -|=== -|Cell A |Cell B -|=== ----- - -.Shorthand markup method for assigning block options (Asciidoctor only) ----- -[%header%footer%autowidth] -|=== -|Cell A |Cell B -|=== ----- - -== Comments - -.Line ----- -include::{includedir}/ex-comment.adoc[tag=line] ----- - -TIP: Single-line comments can be used to divide elements, such as two adjacent lists. - -.Block ----- -include::{includedir}/ex-comment.adoc[tag=bl] ----- - -== Tables - -.Table with a title, three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-base-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-base-h] -==== -<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. -<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. - -.Table with two columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-h] -==== -<1> The `+*+` in the `cols` attribute is the repeat operator. -It means repeat the column specification across the remaining of columns. -In this case, we are repeating the default formatting across 2 columns. -When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. - -.Table with three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-indv-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-indv] -==== -<1> In this example, the `cols` attribute has two functions. -It specifies that this table has three columns, and it sets their relative widths. - -.Table with column containing AsciiDoc content ----- -include::{includedir}/ex-table.adoc[tag=b-col-a] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-a] -==== - -.Table from CSV data ----- -include::{includedir}/ex-table-data.adoc[tag=csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=csv] -==== - -.Table from CSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-csv] -==== - -.Table from CSV data in file ----- -include::{includedir}/ex-table-data.adoc[tag=i-csv] ----- - -.Table from DSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-dsv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-dsv] -==== - -.Table with formatted, aligned and merged cells ----- -include::{includedir}/ex-table-cell.adoc[tag=b-spec] ----- - -[.result] -==== -include::{includedir}/ex-table-cell.adoc[tag=b-spec] -==== - -== UI Macros - -IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. - -.Keyboard shortcuts (inline kbd macro) ----- -include::{includedir}/ex-ui.adoc[tag=key] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=key] -==== - -.Menu selections (inline menu macro) ----- -include::{includedir}/ex-ui.adoc[tag=menu] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=menu] -==== - -.Buttons (inline btn macro) ----- -include::{includedir}/ex-ui.adoc[tag=button] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=button] -==== - -== Attributes and Substitutions - -.Attribute declaration and usage ----- -include::{includedir}/ex-header-attr.adoc[tag=b-attr] ----- - -[.result] -==== -// I have to use a nested doc hack here, otherwise the attributes won't resolve -[.unstyled] -|=== -a| -include::{includedir}/ex-header-attr.adoc[tag=b-attr] -|=== -==== - -.Attribute assignment precedence (highest to lowest) -- Attribute passed to the API or CLI that does not end in `@` -- Attribute defined in the document -- Attribute passed to the API or CLI that ends in `@` -- Intrinsic attribute value (default values) - -TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. - -// Table of predefined attributes for character replacements -include::{includedir}/attrs-charref.adoc[tag=table] - -// Table of environment attributes -include::{includedir}/attrs-env.adoc[tag=table] - -.Named substitutions -include::{includedir}/subs-apply.adoc[tag=group] - -.Counter attributes ----- -include::{includedir}/ex-counter.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-counter.adoc[tag=base] -==== - -== Text Replacement - -// Table of text replacements performed during replacements substitution -include::{includedir}/subs-symbol-repl.adoc[] - -TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. - -== Escaping Text - -.Backslash ----- -include::{includedir}/ex-subs.adoc[tag=b-slash] ----- - -[.result] -==== -include::{includedir}/ex-subs.adoc[tag=b-slash] -==== - -.Passthrough ("`plus for passthrough`") ----- -include::{includedir}/ex-pass.adoc[tag=plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=plus] -==== - -//// -.Double dollar ----- -include::{includedir}/ex-pass.adoc[tag=b-dollar] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-dollar] -==== -//// - -.Raw (triple plus and inline pass macro) ----- -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] -==== - -//// -.Backticks ----- -include::{includedir}/ex-pass.adoc[tag=b-tick] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-tick] -==== -//// - -== Table of Contents (ToC) - -.Document with ToC ----- -include::{includedir}/ex-toc.adoc[tag=base] ----- - -.Document with ToC positioned on the right ----- -include::{includedir}/ex-toc.adoc[tag=pos] ----- - -TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. - -== Bibliography - -.Bibliography with inbound references ----- -include::{includedir}/ex-biblio.adoc[tag=base] ----- - -[.result] -==== -|=== -a| -include::{includedir}/ex-biblio.adoc[tag=base] -|=== -==== - -[#section-footnotes] -== Footnotes - -.Normal and reusable footnotes ----- -include::{includedir}/ex-footnote.adoc[tag=base] ----- - -[.result] -==== -[.unstyled] -|=== -a| -include::{includedir}/ex-footnote.adoc[tag=base] -|=== -==== - -[#markdown-compatibility] -== Markdown Compatibility - -Markdown compatible syntax is only available when using Asciidoctor. - -.Markdown-style headings ----- -include::{includedir}/ex-section.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-md] -==== - -.Fenced code block with syntax highlighting ----- -include::{includedir}/ex-src.adoc[tag=fence] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=fence] -==== - -.Markdown-style blockquote ----- -include::{includedir}/ex-quote.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md] -==== - -.Markdown-style blockquote with block content ----- -include::{includedir}/ex-quote.adoc[tag=md-alt] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md-alt] -==== - -.Markdown-style horizontal rules ----- -include::{includedir}/ex-hr.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=md] -==== - -== User Manual and Help - -To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. -Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. -= AsciiDoc Syntax Quick Reference -Dan Allen; Sarah White -v1.0.4, 2014-08-08 -:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. -:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet -:page-description: {description} -:page-keywords: {keywords} -:page-layout: docs -:page-javascripts: [view-result] -:imagesdir: ../images -:includedir: _includes -:experimental: -:table-caption!: -:example-caption!: -:figure-caption!: -ifndef::env-site[] -:idprefix: -:idseparator: - -:toc: macro -endif::[] -// URLs -:docs: link:../ -ifdef::env-github[:docs: https://asciidoctor.org/docs/] -:user: {docs}user-manual/ -ifdef::env-browser[] -:docs: link:index.adoc -:user: link:user-manual.adoc -endif::[] -:uri-fontawesome: https://fontawesome.com/v4.7.0/ -:uri-icon-in: {user}#inline-icons -:uri-icon-attrs: {user}#size-rotate-and-flip -:uri-video: {user}#video -:uri-checklist: {user}#checklist -:uri-marker: {user}#custom-markers -:uri-list-num: {user}#numbering-styles -:uri-imagesdir: {user}#setting-the-location-of-images -:uri-image-attrs: {user}#putting-images-in-their-place -:uri-toc: {user}#user-toc -:uri-para: {user}#paragraph -:uri-literal: {user}#literal-text-and-blocks -:uri-admon: {user}#admonition -:uri-bold: {user}#bold-and-italic -:uri-quote: {user}#curved -:uri-sub: {user}#subscript-and-superscript -:uri-mono: {user}#mono -:uri-css: {user}#custom-styling-with-attributes -:uri-pass: {user}#pass-macros -:uri-mailinglist: http://discuss.asciidoctor.org -:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references -:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs - -//// -Syntax to cover: -- preface -- index terms -- built-in attributes (such as {author}, {revision}, etc) -- start=n for ordered lists -- horizontal description list -- anchor for any block element -- block metadata (missing example of normal attributes) -- command line reference? perhaps another doc? yes - -PDF TODO: -- add license on title page (legalnotice tag) -- table cell bg -- show example of section levels -- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) -- style sidebar block -//// - -ifdef::basebackend-docbook[] -[preface] -== About -endif::basebackend-docbook[] - -AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. -{description} - -[NOTE] -==== -These examples focus on the output generated by the HTML backend. -AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. -==== - -toc::[] - -== Paragraphs - -.Normal ----- -include::{includedir}/ex-text.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-para] -==== - -.Literal ----- -include::{includedir}/ex-literal.adoc[tag=b-imp] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp] -==== - -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-admon.adoc[tag=b-para] -==== - -NOTE: You can also create <>. - -.Lead paragraph ----- -include::{includedir}/ex-text.adoc[tag=b-lead] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-lead] -==== - -NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. - -.More Paragraph, Admonition and Literal Block Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-para}[Paragraphs] -* {uri-literal}[Literal Text and Blocks] -* {uri-admon}[Admonitions] -**** - -== Formatted Text - -.Bold, Italic, and Monospace ----- -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] -==== - -.Monospace vs codespan ----- -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] -==== - -NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. -Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. -See the <> for details. - -.Marks and Custom Styling ----- -include::{includedir}/ex-text.adoc[tag=css-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=css-all] -==== - -.Superscript and Subscript ----- -include::{includedir}/ex-text.adoc[tag=b-sub-sup] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-sub-sup] -==== - -.Curved Quotation Marks and Apostrophes (Smart Quotes) ----- -include::{includedir}/ex-text.adoc[tag=b-c-quote] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-c-quote] -==== - -.More Text Formatting Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-bold}[Bold and Italic Formatting] -* {uri-quote}[Quotation Marks and Apostrophes] -* {uri-sub}[Subscript and Superscript] -* {uri-mono}[Monospace Formatting] -* {uri-css}[Custom Styling with Attributes] -* {uri-pass}[Passthrough Macros] -**** - -== Document Header - -IMPORTANT: A header is optional. - -CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. - -.Title only ----- -include::{includedir}/ex-header-title.adoc[tag=b-base] ----- - -.Title and author line ----- -include::{includedir}/ex-author.adoc[tag=b-base] ----- - -TIP: Asciidoctor allows multiple authors in the author line. -Use the semi-colon character to separate each author. - -.Title, author line and revision line ----- -include::{includedir}/ex-rev.adoc[tag=b-base] ----- - -IMPORTANT: You cannot have a revision line without an author line. - -.Document header with attributes ----- -include::{includedir}/ex-header-attr.adoc[tag=b-base] ----- - -[#section-titles] -== Section Titles (Headings) - -.Article doctype ----- -include::{includedir}/ex-section.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-base] -==== - -WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. - -NOTE: The number of equal signs matches the heading level in the HTML output. -For example, _Section Level 1_ becomes an `

` heading. - -.Book doctype ----- -include::{includedir}/ex-section.adoc[tag=book] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-book] -==== - -//// -IMPORTANT: There are two other ways to define a section title. -_Their omission is intentional_. -They both require more markup and are therefore unnecessary. -The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. -The reader never sees the extra markup, so why type it? -*Be frugal!* -//// - -.Explicit id ----- -[#primitives-nulls] -== Primitive types and null values ----- - -.Section anchors and links (Asciidoctor only) - -`sectanchors`:: -When this document attribute is set, a section icon anchor appears in front of the section title. - -`sectlinks`:: -When this document attribute is set, the section titles become self-links. -This enables a reader to bookmark the section. - -NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. - -== Include Files - -.Document parts ----- -include::{includedir}/ex-include.adoc[tag=base] ----- - -CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. -Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. - -.Include content from a URI ----- -include::{includedir}/ex-include.adoc[tag=uri] ----- - -NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. -Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. - -== Breaks - -.Hard line break ----- -include::{includedir}/ex-text.adoc[tag=hb-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=hb-all] -==== - -.Thematic break (aka horizontal rule) ----- -include::{includedir}/ex-hr.adoc[tag=in-between] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=in-between] -==== - -.Page break ----- -<<< ----- - -== Lists - -.Unordered, basic ----- -include::{includedir}/ex-ulist.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base] -==== - -.Unordered, basic (alt) ----- -include::{includedir}/ex-ulist.adoc[tag=base-alt] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base-alt] -==== - -NOTE: A blank line is required before and after a list to separated it from other blocks. - -TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. -The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. - -.Unordered, max nesting ----- -include::{includedir}/ex-ulist.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=max] -==== - -TIP: The unordered list marker can be changed using {uri-marker}[block styles]. - -.Ordered, basic ----- -include::{includedir}/ex-o-list.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=b-base] -==== - -NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. - -.Ordered, nested ----- -include::{includedir}/ex-o-list.adoc[tag=nest] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=nest] -==== - -.Ordered, max nesting ----- -include::{includedir}/ex-o-list.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=max] -==== - -TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. - -.Checklist ----- -include::{includedir}/ex-ulist.adoc[tag=check] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=check] -==== - -TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. - -.Description, single-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base] -==== - -.Description, multi-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] -==== - -.Q&A ----- -include::{includedir}/ex-dlist.adoc[tag=qa] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=qa] -==== - -.Mixed ----- -include::{includedir}/ex-dlist.adoc[tag=3-mix] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=3-mix] -==== - -TIP: Lists can be indented. -Leading whitespace is not significant. - -.Complex content in outline lists ----- -include::{includedir}/ex-ulist.adoc[tag=b-complex] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=b-complex] -==== - -== Links - -.External ----- -include::{includedir}/ex-url.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-base] -==== - -.With spaces and special characters ----- -include::{includedir}/ex-url.adoc[tag=b-spaces] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-spaces] -==== - -.Windows path ----- -include::{includedir}/ex-url.adoc[tag=b-windows] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-windows] -==== - -.Relative ----- -link:index.html[Docs] ----- - -[.result] -==== -link:index.html[Docs] -==== - -.Email and IRC ----- -include::{includedir}/ex-url.adoc[tag=b-scheme] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-scheme] -==== - -.Link with attributes (Asciidoctor only) ----- -include::{includedir}/ex-url.adoc[tag=b-linkattrs] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-linkattrs] -==== - -NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. -To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. -Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. -When attribute parsing is enabled, you must quote the link text if it contains a comma. - -.Inline anchors ----- -include::{includedir}/ex-xref.adoc[tag=anchor] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=anchor] -==== - -.Internal cross references ----- -include::{includedir}/ex-xref.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=b-base] -==== - -.Inter-document cross references (Asciidoctor only) ----- -include::{includedir}/ex-xref.adoc[tag=b-inter] ----- - -== Images - -Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. -You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. - -The `imagesdir` attribute can be an absolute path, relative path, or base URL. -When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. - -.Block ----- -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] -==== - -.Inline ----- -include::{includedir}/ex-image.adoc[tag=in] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in] -==== - -IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. -(All macros follow this pattern). -You use an inline image when you need to place the image in a line of text. -Otherwise, you should prefer the block form. - -.Inline image with positioning role ----- -include::{includedir}/ex-image.adoc[tag=in-role] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in-role] -==== - -TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. - -.Embedded ----- -include::{includedir}/ex-image.adoc[tag=data] ----- - -NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. - -TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. - -== Videos - -.Block ----- -include::{includedir}/ex-video.adoc[tag=base] - -include::{includedir}/ex-video.adoc[tag=attr] ----- - -.Embedded Youtube video ----- -include::{includedir}/ex-video.adoc[tag=you] ----- - -.Embedded Vimeo video ----- -include::{includedir}/ex-video.adoc[tag=vim] ----- - -TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. - -== Source Code - -.Inline (monospace only) ----- -include::{includedir}/ex-text.adoc[tag=b-mono-code] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-mono-code] -==== - -.Inline (literal) ----- -include::{includedir}/ex-pass.adoc[tag=backtick-plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=backtick-plus] -==== - -.Literal line ----- -include::{includedir}/ex-literal.adoc[tag=b-imp-code] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp-code] -==== - -.Literal block ----- -include::{includedir}/ex-literal.adoc[tag=b-block] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-block] -==== - -[listing] -.Listing block with title, no syntax highlighting -.... -include::{includedir}/ex-listing.adoc[tag=b-base] -.... - -[.result] -==== -include::{includedir}/ex-listing.adoc[tag=b-base] -==== - -[listing] -.Code block with title and syntax highlighting -.... -include::{includedir}/ex-src.adoc[tag=src-base] -.... - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-base] -==== - -[listing,subs=specialchars] -.Code block with callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-src] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-src] -==== - -[listing,subs=specialchars] -.Code block with non-selectable callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -==== - -[listing,subs=specialchars] -.XML code block with a non-selectable callout -.... -include::{includedir}/ex-callout.adoc[tag=source-xml] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=source-xml] -==== - -[listing] -.Code block sourced from file -.... -include::{includedir}/ex-src.adoc[tag=src-inc] -.... - -[listing] -.Code block sourced from file relative to source directory -.... -include::{includedir}/ex-src.adoc[tag=rel] -.... - -[listing] -.Strip leading indentation from source -.... -include::{includedir}/ex-src.adoc[tag=ind] -.... - -[NOTE] -==== -* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). -* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. -==== - -.Code block without delimiters (no blank lines) ----- -include::{includedir}/ex-src.adoc[tag=src-para] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-para] -==== - -[IMPORTANT] -.Enabling the syntax highlighter -==== -Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. - - :source-highlighter: pygments - -The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. -==== - -== More Delimited Blocks - -.Sidebar ----- -include::{includedir}/ex-sidebar.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-sidebar.adoc[tag=base] -==== - -NOTE: Any block can have a title, positioned above the block. -A block title is a line of text that starts with a dot. -The dot cannot be followed by a space. - -.Example ----- -include::{includedir}/ex-example.adoc[tag=base] ----- - -[example.result] --- -include::{includedir}/ex-example.adoc[tag=base] --- - -[#admon-bl] -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-bl] ----- - -[.result] -===== -include::{includedir}/ex-admon.adoc[tag=b-bl] -===== - -[TIP] -.Admonition and callout icons -==== -Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. - -To use this feature, set the value of the `icons` document attribute to `font`. -Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. - -Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. -==== - -.Blockquote ----- -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] -==== - -.Abbreviated blockquote (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=abbr] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=abbr] -==== - -.Air quotes: the best thing since fenced code blocks (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=air] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=air] -==== - -.Passthrough ----- -include::{includedir}/ex-pass.adoc[tag=b-bl] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-bl] -==== - -.Open ----- -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] ----- - -[.result] -==== -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] -==== - -[listing] -.Custom substitutions -.... -include::{includedir}/ex-listing.adoc[tag=subs] -.... - -[.result] -==== -// the attribute value is hard-coded in this result since the example depends -// on a hypothetical document attribute -include::{includedir}/ex-listing.adoc[tag=subs-out] -==== - -== Block Id, Role and Options - -.Traditional (longhand) markup method for assigning block id and role ----- -[[goals]] -[role="incremental"] -* Goal 1 -* Goal 2 ----- - -.Shorthand markup method for assigning block id and role (Asciidoctor only) ----- -[#goals.incremental] -* Goal 1 -* Goal 2 ----- - -[TIP] -==== -* To specify multiple roles using the shorthand syntax, separate them by dots. -* The order of `id` and `role` values in the shorthand syntax does not matter. -==== - -.Traditional (longhand) markup method for assigning quoted text anchor (id) and role ----- -[[free_the_world]][big goal]_free the world_ ----- - -.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) ----- -[#free_the_world.big.goal]_free the world_ ----- - -.Role assigned to text enclosed in backticks ----- -[.rolename]`monospace text` ----- - -.Traditional (longhand) markup method for assigning block options ----- -[options="header,footer,autowidth"] -|=== -|Cell A |Cell B -|=== ----- - -.Shorthand markup method for assigning block options (Asciidoctor only) ----- -[%header%footer%autowidth] -|=== -|Cell A |Cell B -|=== ----- - -== Comments - -.Line ----- -include::{includedir}/ex-comment.adoc[tag=line] ----- - -TIP: Single-line comments can be used to divide elements, such as two adjacent lists. - -.Block ----- -include::{includedir}/ex-comment.adoc[tag=bl] ----- - -== Tables - -.Table with a title, three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-base-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-base-h] -==== -<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. -<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. - -.Table with two columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-h] -==== -<1> The `+*+` in the `cols` attribute is the repeat operator. -It means repeat the column specification across the remaining of columns. -In this case, we are repeating the default formatting across 2 columns. -When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. - -.Table with three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-indv-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-indv] -==== -<1> In this example, the `cols` attribute has two functions. -It specifies that this table has three columns, and it sets their relative widths. - -.Table with column containing AsciiDoc content ----- -include::{includedir}/ex-table.adoc[tag=b-col-a] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-a] -==== - -.Table from CSV data ----- -include::{includedir}/ex-table-data.adoc[tag=csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=csv] -==== - -.Table from CSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-csv] -==== - -.Table from CSV data in file ----- -include::{includedir}/ex-table-data.adoc[tag=i-csv] ----- - -.Table from DSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-dsv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-dsv] -==== - -.Table with formatted, aligned and merged cells ----- -include::{includedir}/ex-table-cell.adoc[tag=b-spec] ----- - -[.result] -==== -include::{includedir}/ex-table-cell.adoc[tag=b-spec] -==== - -== UI Macros - -IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. - -.Keyboard shortcuts (inline kbd macro) ----- -include::{includedir}/ex-ui.adoc[tag=key] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=key] -==== - -.Menu selections (inline menu macro) ----- -include::{includedir}/ex-ui.adoc[tag=menu] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=menu] -==== - -.Buttons (inline btn macro) ----- -include::{includedir}/ex-ui.adoc[tag=button] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=button] -==== - -== Attributes and Substitutions - -.Attribute declaration and usage ----- -include::{includedir}/ex-header-attr.adoc[tag=b-attr] ----- - -[.result] -==== -// I have to use a nested doc hack here, otherwise the attributes won't resolve -[.unstyled] -|=== -a| -include::{includedir}/ex-header-attr.adoc[tag=b-attr] -|=== -==== - -.Attribute assignment precedence (highest to lowest) -- Attribute passed to the API or CLI that does not end in `@` -- Attribute defined in the document -- Attribute passed to the API or CLI that ends in `@` -- Intrinsic attribute value (default values) - -TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. - -// Table of predefined attributes for character replacements -include::{includedir}/attrs-charref.adoc[tag=table] - -// Table of environment attributes -include::{includedir}/attrs-env.adoc[tag=table] - -.Named substitutions -include::{includedir}/subs-apply.adoc[tag=group] - -.Counter attributes ----- -include::{includedir}/ex-counter.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-counter.adoc[tag=base] -==== - -== Text Replacement - -// Table of text replacements performed during replacements substitution -include::{includedir}/subs-symbol-repl.adoc[] - -TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. - -== Escaping Text - -.Backslash ----- -include::{includedir}/ex-subs.adoc[tag=b-slash] ----- - -[.result] -==== -include::{includedir}/ex-subs.adoc[tag=b-slash] -==== - -.Passthrough ("`plus for passthrough`") ----- -include::{includedir}/ex-pass.adoc[tag=plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=plus] -==== - -//// -.Double dollar ----- -include::{includedir}/ex-pass.adoc[tag=b-dollar] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-dollar] -==== -//// - -.Raw (triple plus and inline pass macro) ----- -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] -==== - -//// -.Backticks ----- -include::{includedir}/ex-pass.adoc[tag=b-tick] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-tick] -==== -//// - -== Table of Contents (ToC) - -.Document with ToC ----- -include::{includedir}/ex-toc.adoc[tag=base] ----- - -.Document with ToC positioned on the right ----- -include::{includedir}/ex-toc.adoc[tag=pos] ----- - -TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. - -== Bibliography - -.Bibliography with inbound references ----- -include::{includedir}/ex-biblio.adoc[tag=base] ----- - -[.result] -==== -|=== -a| -include::{includedir}/ex-biblio.adoc[tag=base] -|=== -==== - -[#section-footnotes] -== Footnotes - -.Normal and reusable footnotes ----- -include::{includedir}/ex-footnote.adoc[tag=base] ----- - -[.result] -==== -[.unstyled] -|=== -a| -include::{includedir}/ex-footnote.adoc[tag=base] -|=== -==== - -[#markdown-compatibility] -== Markdown Compatibility - -Markdown compatible syntax is only available when using Asciidoctor. - -.Markdown-style headings ----- -include::{includedir}/ex-section.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-md] -==== - -.Fenced code block with syntax highlighting ----- -include::{includedir}/ex-src.adoc[tag=fence] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=fence] -==== - -.Markdown-style blockquote ----- -include::{includedir}/ex-quote.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md] -==== - -.Markdown-style blockquote with block content ----- -include::{includedir}/ex-quote.adoc[tag=md-alt] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md-alt] -==== - -.Markdown-style horizontal rules ----- -include::{includedir}/ex-hr.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=md] -==== - -== User Manual and Help - -To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. -Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. -= AsciiDoc Syntax Quick Reference -Dan Allen; Sarah White -v1.0.4, 2014-08-08 -:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. -:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet -:page-description: {description} -:page-keywords: {keywords} -:page-layout: docs -:page-javascripts: [view-result] -:imagesdir: ../images -:includedir: _includes -:experimental: -:table-caption!: -:example-caption!: -:figure-caption!: -ifndef::env-site[] -:idprefix: -:idseparator: - -:toc: macro -endif::[] -// URLs -:docs: link:../ -ifdef::env-github[:docs: https://asciidoctor.org/docs/] -:user: {docs}user-manual/ -ifdef::env-browser[] -:docs: link:index.adoc -:user: link:user-manual.adoc -endif::[] -:uri-fontawesome: https://fontawesome.com/v4.7.0/ -:uri-icon-in: {user}#inline-icons -:uri-icon-attrs: {user}#size-rotate-and-flip -:uri-video: {user}#video -:uri-checklist: {user}#checklist -:uri-marker: {user}#custom-markers -:uri-list-num: {user}#numbering-styles -:uri-imagesdir: {user}#setting-the-location-of-images -:uri-image-attrs: {user}#putting-images-in-their-place -:uri-toc: {user}#user-toc -:uri-para: {user}#paragraph -:uri-literal: {user}#literal-text-and-blocks -:uri-admon: {user}#admonition -:uri-bold: {user}#bold-and-italic -:uri-quote: {user}#curved -:uri-sub: {user}#subscript-and-superscript -:uri-mono: {user}#mono -:uri-css: {user}#custom-styling-with-attributes -:uri-pass: {user}#pass-macros -:uri-mailinglist: http://discuss.asciidoctor.org -:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references -:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs - -//// -Syntax to cover: -- preface -- index terms -- built-in attributes (such as {author}, {revision}, etc) -- start=n for ordered lists -- horizontal description list -- anchor for any block element -- block metadata (missing example of normal attributes) -- command line reference? perhaps another doc? yes - -PDF TODO: -- add license on title page (legalnotice tag) -- table cell bg -- show example of section levels -- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) -- style sidebar block -//// - -ifdef::basebackend-docbook[] -[preface] -== About -endif::basebackend-docbook[] - -AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. -{description} - -[NOTE] -==== -These examples focus on the output generated by the HTML backend. -AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. -==== - -toc::[] - -== Paragraphs - -.Normal ----- -include::{includedir}/ex-text.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-para] -==== - -.Literal ----- -include::{includedir}/ex-literal.adoc[tag=b-imp] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp] -==== - -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-admon.adoc[tag=b-para] -==== - -NOTE: You can also create <>. - -.Lead paragraph ----- -include::{includedir}/ex-text.adoc[tag=b-lead] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-lead] -==== - -NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. - -.More Paragraph, Admonition and Literal Block Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-para}[Paragraphs] -* {uri-literal}[Literal Text and Blocks] -* {uri-admon}[Admonitions] -**** - -== Formatted Text - -.Bold, Italic, and Monospace ----- -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] -==== - -.Monospace vs codespan ----- -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] -==== - -NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. -Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. -See the <> for details. - -.Marks and Custom Styling ----- -include::{includedir}/ex-text.adoc[tag=css-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=css-all] -==== - -.Superscript and Subscript ----- -include::{includedir}/ex-text.adoc[tag=b-sub-sup] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-sub-sup] -==== - -.Curved Quotation Marks and Apostrophes (Smart Quotes) ----- -include::{includedir}/ex-text.adoc[tag=b-c-quote] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-c-quote] -==== - -.More Text Formatting Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-bold}[Bold and Italic Formatting] -* {uri-quote}[Quotation Marks and Apostrophes] -* {uri-sub}[Subscript and Superscript] -* {uri-mono}[Monospace Formatting] -* {uri-css}[Custom Styling with Attributes] -* {uri-pass}[Passthrough Macros] -**** - -== Document Header - -IMPORTANT: A header is optional. - -CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. - -.Title only ----- -include::{includedir}/ex-header-title.adoc[tag=b-base] ----- - -.Title and author line ----- -include::{includedir}/ex-author.adoc[tag=b-base] ----- - -TIP: Asciidoctor allows multiple authors in the author line. -Use the semi-colon character to separate each author. - -.Title, author line and revision line ----- -include::{includedir}/ex-rev.adoc[tag=b-base] ----- - -IMPORTANT: You cannot have a revision line without an author line. - -.Document header with attributes ----- -include::{includedir}/ex-header-attr.adoc[tag=b-base] ----- - -[#section-titles] -== Section Titles (Headings) - -.Article doctype ----- -include::{includedir}/ex-section.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-base] -==== - -WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. - -NOTE: The number of equal signs matches the heading level in the HTML output. -For example, _Section Level 1_ becomes an `

` heading. - -.Book doctype ----- -include::{includedir}/ex-section.adoc[tag=book] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-book] -==== - -//// -IMPORTANT: There are two other ways to define a section title. -_Their omission is intentional_. -They both require more markup and are therefore unnecessary. -The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. -The reader never sees the extra markup, so why type it? -*Be frugal!* -//// - -.Explicit id ----- -[#primitives-nulls] -== Primitive types and null values ----- - -.Section anchors and links (Asciidoctor only) - -`sectanchors`:: -When this document attribute is set, a section icon anchor appears in front of the section title. - -`sectlinks`:: -When this document attribute is set, the section titles become self-links. -This enables a reader to bookmark the section. - -NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. - -== Include Files - -.Document parts ----- -include::{includedir}/ex-include.adoc[tag=base] ----- - -CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. -Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. - -.Include content from a URI ----- -include::{includedir}/ex-include.adoc[tag=uri] ----- - -NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. -Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. - -== Breaks - -.Hard line break ----- -include::{includedir}/ex-text.adoc[tag=hb-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=hb-all] -==== - -.Thematic break (aka horizontal rule) ----- -include::{includedir}/ex-hr.adoc[tag=in-between] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=in-between] -==== - -.Page break ----- -<<< ----- - -== Lists - -.Unordered, basic ----- -include::{includedir}/ex-ulist.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base] -==== - -.Unordered, basic (alt) ----- -include::{includedir}/ex-ulist.adoc[tag=base-alt] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base-alt] -==== - -NOTE: A blank line is required before and after a list to separated it from other blocks. - -TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. -The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. - -.Unordered, max nesting ----- -include::{includedir}/ex-ulist.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=max] -==== - -TIP: The unordered list marker can be changed using {uri-marker}[block styles]. - -.Ordered, basic ----- -include::{includedir}/ex-o-list.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=b-base] -==== - -NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. - -.Ordered, nested ----- -include::{includedir}/ex-o-list.adoc[tag=nest] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=nest] -==== - -.Ordered, max nesting ----- -include::{includedir}/ex-o-list.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=max] -==== - -TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. - -.Checklist ----- -include::{includedir}/ex-ulist.adoc[tag=check] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=check] -==== - -TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. - -.Description, single-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base] -==== - -.Description, multi-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] -==== - -.Q&A ----- -include::{includedir}/ex-dlist.adoc[tag=qa] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=qa] -==== - -.Mixed ----- -include::{includedir}/ex-dlist.adoc[tag=3-mix] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=3-mix] -==== - -TIP: Lists can be indented. -Leading whitespace is not significant. - -.Complex content in outline lists ----- -include::{includedir}/ex-ulist.adoc[tag=b-complex] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=b-complex] -==== - -== Links - -.External ----- -include::{includedir}/ex-url.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-base] -==== - -.With spaces and special characters ----- -include::{includedir}/ex-url.adoc[tag=b-spaces] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-spaces] -==== - -.Windows path ----- -include::{includedir}/ex-url.adoc[tag=b-windows] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-windows] -==== - -.Relative ----- -link:index.html[Docs] ----- - -[.result] -==== -link:index.html[Docs] -==== - -.Email and IRC ----- -include::{includedir}/ex-url.adoc[tag=b-scheme] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-scheme] -==== - -.Link with attributes (Asciidoctor only) ----- -include::{includedir}/ex-url.adoc[tag=b-linkattrs] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-linkattrs] -==== - -NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. -To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. -Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. -When attribute parsing is enabled, you must quote the link text if it contains a comma. - -.Inline anchors ----- -include::{includedir}/ex-xref.adoc[tag=anchor] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=anchor] -==== - -.Internal cross references ----- -include::{includedir}/ex-xref.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=b-base] -==== - -.Inter-document cross references (Asciidoctor only) ----- -include::{includedir}/ex-xref.adoc[tag=b-inter] ----- - -== Images - -Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. -You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. - -The `imagesdir` attribute can be an absolute path, relative path, or base URL. -When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. - -.Block ----- -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] -==== - -.Inline ----- -include::{includedir}/ex-image.adoc[tag=in] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in] -==== - -IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. -(All macros follow this pattern). -You use an inline image when you need to place the image in a line of text. -Otherwise, you should prefer the block form. - -.Inline image with positioning role ----- -include::{includedir}/ex-image.adoc[tag=in-role] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in-role] -==== - -TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. - -.Embedded ----- -include::{includedir}/ex-image.adoc[tag=data] ----- - -NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. - -TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. - -== Videos - -.Block ----- -include::{includedir}/ex-video.adoc[tag=base] - -include::{includedir}/ex-video.adoc[tag=attr] ----- - -.Embedded Youtube video ----- -include::{includedir}/ex-video.adoc[tag=you] ----- - -.Embedded Vimeo video ----- -include::{includedir}/ex-video.adoc[tag=vim] ----- - -TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. - -== Source Code - -.Inline (monospace only) ----- -include::{includedir}/ex-text.adoc[tag=b-mono-code] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-mono-code] -==== - -.Inline (literal) ----- -include::{includedir}/ex-pass.adoc[tag=backtick-plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=backtick-plus] -==== - -.Literal line ----- -include::{includedir}/ex-literal.adoc[tag=b-imp-code] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp-code] -==== - -.Literal block ----- -include::{includedir}/ex-literal.adoc[tag=b-block] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-block] -==== - -[listing] -.Listing block with title, no syntax highlighting -.... -include::{includedir}/ex-listing.adoc[tag=b-base] -.... - -[.result] -==== -include::{includedir}/ex-listing.adoc[tag=b-base] -==== - -[listing] -.Code block with title and syntax highlighting -.... -include::{includedir}/ex-src.adoc[tag=src-base] -.... - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-base] -==== - -[listing,subs=specialchars] -.Code block with callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-src] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-src] -==== - -[listing,subs=specialchars] -.Code block with non-selectable callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -==== - -[listing,subs=specialchars] -.XML code block with a non-selectable callout -.... -include::{includedir}/ex-callout.adoc[tag=source-xml] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=source-xml] -==== - -[listing] -.Code block sourced from file -.... -include::{includedir}/ex-src.adoc[tag=src-inc] -.... - -[listing] -.Code block sourced from file relative to source directory -.... -include::{includedir}/ex-src.adoc[tag=rel] -.... - -[listing] -.Strip leading indentation from source -.... -include::{includedir}/ex-src.adoc[tag=ind] -.... - -[NOTE] -==== -* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). -* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. -==== - -.Code block without delimiters (no blank lines) ----- -include::{includedir}/ex-src.adoc[tag=src-para] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-para] -==== - -[IMPORTANT] -.Enabling the syntax highlighter -==== -Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. - - :source-highlighter: pygments - -The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. -==== - -== More Delimited Blocks - -.Sidebar ----- -include::{includedir}/ex-sidebar.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-sidebar.adoc[tag=base] -==== - -NOTE: Any block can have a title, positioned above the block. -A block title is a line of text that starts with a dot. -The dot cannot be followed by a space. - -.Example ----- -include::{includedir}/ex-example.adoc[tag=base] ----- - -[example.result] --- -include::{includedir}/ex-example.adoc[tag=base] --- - -[#admon-bl] -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-bl] ----- - -[.result] -===== -include::{includedir}/ex-admon.adoc[tag=b-bl] -===== - -[TIP] -.Admonition and callout icons -==== -Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. - -To use this feature, set the value of the `icons` document attribute to `font`. -Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. - -Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. -==== - -.Blockquote ----- -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] -==== - -.Abbreviated blockquote (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=abbr] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=abbr] -==== - -.Air quotes: the best thing since fenced code blocks (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=air] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=air] -==== - -.Passthrough ----- -include::{includedir}/ex-pass.adoc[tag=b-bl] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-bl] -==== - -.Open ----- -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] ----- - -[.result] -==== -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] -==== - -[listing] -.Custom substitutions -.... -include::{includedir}/ex-listing.adoc[tag=subs] -.... - -[.result] -==== -// the attribute value is hard-coded in this result since the example depends -// on a hypothetical document attribute -include::{includedir}/ex-listing.adoc[tag=subs-out] -==== - -== Block Id, Role and Options - -.Traditional (longhand) markup method for assigning block id and role ----- -[[goals]] -[role="incremental"] -* Goal 1 -* Goal 2 ----- - -.Shorthand markup method for assigning block id and role (Asciidoctor only) ----- -[#goals.incremental] -* Goal 1 -* Goal 2 ----- - -[TIP] -==== -* To specify multiple roles using the shorthand syntax, separate them by dots. -* The order of `id` and `role` values in the shorthand syntax does not matter. -==== - -.Traditional (longhand) markup method for assigning quoted text anchor (id) and role ----- -[[free_the_world]][big goal]_free the world_ ----- - -.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) ----- -[#free_the_world.big.goal]_free the world_ ----- - -.Role assigned to text enclosed in backticks ----- -[.rolename]`monospace text` ----- - -.Traditional (longhand) markup method for assigning block options ----- -[options="header,footer,autowidth"] -|=== -|Cell A |Cell B -|=== ----- - -.Shorthand markup method for assigning block options (Asciidoctor only) ----- -[%header%footer%autowidth] -|=== -|Cell A |Cell B -|=== ----- - -== Comments - -.Line ----- -include::{includedir}/ex-comment.adoc[tag=line] ----- - -TIP: Single-line comments can be used to divide elements, such as two adjacent lists. - -.Block ----- -include::{includedir}/ex-comment.adoc[tag=bl] ----- - -== Tables - -.Table with a title, three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-base-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-base-h] -==== -<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. -<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. - -.Table with two columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-h] -==== -<1> The `+*+` in the `cols` attribute is the repeat operator. -It means repeat the column specification across the remaining of columns. -In this case, we are repeating the default formatting across 2 columns. -When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. - -.Table with three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-indv-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-indv] -==== -<1> In this example, the `cols` attribute has two functions. -It specifies that this table has three columns, and it sets their relative widths. - -.Table with column containing AsciiDoc content ----- -include::{includedir}/ex-table.adoc[tag=b-col-a] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-a] -==== - -.Table from CSV data ----- -include::{includedir}/ex-table-data.adoc[tag=csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=csv] -==== - -.Table from CSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-csv] -==== - -.Table from CSV data in file ----- -include::{includedir}/ex-table-data.adoc[tag=i-csv] ----- - -.Table from DSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-dsv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-dsv] -==== - -.Table with formatted, aligned and merged cells ----- -include::{includedir}/ex-table-cell.adoc[tag=b-spec] ----- - -[.result] -==== -include::{includedir}/ex-table-cell.adoc[tag=b-spec] -==== - -== UI Macros - -IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. - -.Keyboard shortcuts (inline kbd macro) ----- -include::{includedir}/ex-ui.adoc[tag=key] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=key] -==== - -.Menu selections (inline menu macro) ----- -include::{includedir}/ex-ui.adoc[tag=menu] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=menu] -==== - -.Buttons (inline btn macro) ----- -include::{includedir}/ex-ui.adoc[tag=button] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=button] -==== - -== Attributes and Substitutions - -.Attribute declaration and usage ----- -include::{includedir}/ex-header-attr.adoc[tag=b-attr] ----- - -[.result] -==== -// I have to use a nested doc hack here, otherwise the attributes won't resolve -[.unstyled] -|=== -a| -include::{includedir}/ex-header-attr.adoc[tag=b-attr] -|=== -==== - -.Attribute assignment precedence (highest to lowest) -- Attribute passed to the API or CLI that does not end in `@` -- Attribute defined in the document -- Attribute passed to the API or CLI that ends in `@` -- Intrinsic attribute value (default values) - -TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. - -// Table of predefined attributes for character replacements -include::{includedir}/attrs-charref.adoc[tag=table] - -// Table of environment attributes -include::{includedir}/attrs-env.adoc[tag=table] - -.Named substitutions -include::{includedir}/subs-apply.adoc[tag=group] - -.Counter attributes ----- -include::{includedir}/ex-counter.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-counter.adoc[tag=base] -==== - -== Text Replacement - -// Table of text replacements performed during replacements substitution -include::{includedir}/subs-symbol-repl.adoc[] - -TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. - -== Escaping Text - -.Backslash ----- -include::{includedir}/ex-subs.adoc[tag=b-slash] ----- - -[.result] -==== -include::{includedir}/ex-subs.adoc[tag=b-slash] -==== - -.Passthrough ("`plus for passthrough`") ----- -include::{includedir}/ex-pass.adoc[tag=plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=plus] -==== - -//// -.Double dollar ----- -include::{includedir}/ex-pass.adoc[tag=b-dollar] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-dollar] -==== -//// - -.Raw (triple plus and inline pass macro) ----- -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] -==== - -//// -.Backticks ----- -include::{includedir}/ex-pass.adoc[tag=b-tick] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-tick] -==== -//// - -== Table of Contents (ToC) - -.Document with ToC ----- -include::{includedir}/ex-toc.adoc[tag=base] ----- - -.Document with ToC positioned on the right ----- -include::{includedir}/ex-toc.adoc[tag=pos] ----- - -TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. - -== Bibliography - -.Bibliography with inbound references ----- -include::{includedir}/ex-biblio.adoc[tag=base] ----- - -[.result] -==== -|=== -a| -include::{includedir}/ex-biblio.adoc[tag=base] -|=== -==== - -[#section-footnotes] -== Footnotes - -.Normal and reusable footnotes ----- -include::{includedir}/ex-footnote.adoc[tag=base] ----- - -[.result] -==== -[.unstyled] -|=== -a| -include::{includedir}/ex-footnote.adoc[tag=base] -|=== -==== - -[#markdown-compatibility] -== Markdown Compatibility - -Markdown compatible syntax is only available when using Asciidoctor. - -.Markdown-style headings ----- -include::{includedir}/ex-section.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-md] -==== - -.Fenced code block with syntax highlighting ----- -include::{includedir}/ex-src.adoc[tag=fence] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=fence] -==== - -.Markdown-style blockquote ----- -include::{includedir}/ex-quote.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md] -==== - -.Markdown-style blockquote with block content ----- -include::{includedir}/ex-quote.adoc[tag=md-alt] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md-alt] -==== - -.Markdown-style horizontal rules ----- -include::{includedir}/ex-hr.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=md] -==== - -== User Manual and Help - -To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. -Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. -= AsciiDoc Syntax Quick Reference -Dan Allen; Sarah White -v1.0.4, 2014-08-08 -:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. -:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet -:page-description: {description} -:page-keywords: {keywords} -:page-layout: docs -:page-javascripts: [view-result] -:imagesdir: ../images -:includedir: _includes -:experimental: -:table-caption!: -:example-caption!: -:figure-caption!: -ifndef::env-site[] -:idprefix: -:idseparator: - -:toc: macro -endif::[] -// URLs -:docs: link:../ -ifdef::env-github[:docs: https://asciidoctor.org/docs/] -:user: {docs}user-manual/ -ifdef::env-browser[] -:docs: link:index.adoc -:user: link:user-manual.adoc -endif::[] -:uri-fontawesome: https://fontawesome.com/v4.7.0/ -:uri-icon-in: {user}#inline-icons -:uri-icon-attrs: {user}#size-rotate-and-flip -:uri-video: {user}#video -:uri-checklist: {user}#checklist -:uri-marker: {user}#custom-markers -:uri-list-num: {user}#numbering-styles -:uri-imagesdir: {user}#setting-the-location-of-images -:uri-image-attrs: {user}#putting-images-in-their-place -:uri-toc: {user}#user-toc -:uri-para: {user}#paragraph -:uri-literal: {user}#literal-text-and-blocks -:uri-admon: {user}#admonition -:uri-bold: {user}#bold-and-italic -:uri-quote: {user}#curved -:uri-sub: {user}#subscript-and-superscript -:uri-mono: {user}#mono -:uri-css: {user}#custom-styling-with-attributes -:uri-pass: {user}#pass-macros -:uri-mailinglist: http://discuss.asciidoctor.org -:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references -:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs - -//// -Syntax to cover: -- preface -- index terms -- built-in attributes (such as {author}, {revision}, etc) -- start=n for ordered lists -- horizontal description list -- anchor for any block element -- block metadata (missing example of normal attributes) -- command line reference? perhaps another doc? yes - -PDF TODO: -- add license on title page (legalnotice tag) -- table cell bg -- show example of section levels -- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) -- style sidebar block -//// - -ifdef::basebackend-docbook[] -[preface] -== About -endif::basebackend-docbook[] - -AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. -{description} - -[NOTE] -==== -These examples focus on the output generated by the HTML backend. -AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. -==== - -toc::[] - -== Paragraphs - -.Normal ----- -include::{includedir}/ex-text.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-para] -==== - -.Literal ----- -include::{includedir}/ex-literal.adoc[tag=b-imp] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp] -==== - -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-para] ----- - -[.result] -==== -include::{includedir}/ex-admon.adoc[tag=b-para] -==== - -NOTE: You can also create <>. - -.Lead paragraph ----- -include::{includedir}/ex-text.adoc[tag=b-lead] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-lead] -==== - -NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. - -.More Paragraph, Admonition and Literal Block Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-para}[Paragraphs] -* {uri-literal}[Literal Text and Blocks] -* {uri-admon}[Admonitions] -**** - -== Formatted Text - -.Bold, Italic, and Monospace ----- -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] -==== - -.Monospace vs codespan ----- -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] -==== - -NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. -Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. -See the <> for details. - -.Marks and Custom Styling ----- -include::{includedir}/ex-text.adoc[tag=css-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=css-all] -==== - -.Superscript and Subscript ----- -include::{includedir}/ex-text.adoc[tag=b-sub-sup] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-sub-sup] -==== - -.Curved Quotation Marks and Apostrophes (Smart Quotes) ----- -include::{includedir}/ex-text.adoc[tag=b-c-quote] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-c-quote] -==== - -.More Text Formatting Examples -**** -See these sections in the Asciidoctor User Manual for more information and examples. - -* {uri-bold}[Bold and Italic Formatting] -* {uri-quote}[Quotation Marks and Apostrophes] -* {uri-sub}[Subscript and Superscript] -* {uri-mono}[Monospace Formatting] -* {uri-css}[Custom Styling with Attributes] -* {uri-pass}[Passthrough Macros] -**** - -== Document Header - -IMPORTANT: A header is optional. - -CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. - -.Title only ----- -include::{includedir}/ex-header-title.adoc[tag=b-base] ----- - -.Title and author line ----- -include::{includedir}/ex-author.adoc[tag=b-base] ----- - -TIP: Asciidoctor allows multiple authors in the author line. -Use the semi-colon character to separate each author. - -.Title, author line and revision line ----- -include::{includedir}/ex-rev.adoc[tag=b-base] ----- - -IMPORTANT: You cannot have a revision line without an author line. - -.Document header with attributes ----- -include::{includedir}/ex-header-attr.adoc[tag=b-base] ----- - -[#section-titles] -== Section Titles (Headings) - -.Article doctype ----- -include::{includedir}/ex-section.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-base] -==== - -WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. - -NOTE: The number of equal signs matches the heading level in the HTML output. -For example, _Section Level 1_ becomes an `

` heading. - -.Book doctype ----- -include::{includedir}/ex-section.adoc[tag=book] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-book] -==== - -//// -IMPORTANT: There are two other ways to define a section title. -_Their omission is intentional_. -They both require more markup and are therefore unnecessary. -The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. -The reader never sees the extra markup, so why type it? -*Be frugal!* -//// - -.Explicit id ----- -[#primitives-nulls] -== Primitive types and null values ----- - -.Section anchors and links (Asciidoctor only) - -`sectanchors`:: -When this document attribute is set, a section icon anchor appears in front of the section title. - -`sectlinks`:: -When this document attribute is set, the section titles become self-links. -This enables a reader to bookmark the section. - -NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. - -== Include Files - -.Document parts ----- -include::{includedir}/ex-include.adoc[tag=base] ----- - -CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. -Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. - -.Include content from a URI ----- -include::{includedir}/ex-include.adoc[tag=uri] ----- - -NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. -Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. - -== Breaks - -.Hard line break ----- -include::{includedir}/ex-text.adoc[tag=hb-all] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=hb-all] -==== - -.Thematic break (aka horizontal rule) ----- -include::{includedir}/ex-hr.adoc[tag=in-between] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=in-between] -==== - -.Page break ----- -<<< ----- - -== Lists - -.Unordered, basic ----- -include::{includedir}/ex-ulist.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base] -==== - -.Unordered, basic (alt) ----- -include::{includedir}/ex-ulist.adoc[tag=base-alt] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=base-alt] -==== - -NOTE: A blank line is required before and after a list to separated it from other blocks. - -TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. -The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. - -.Unordered, max nesting ----- -include::{includedir}/ex-ulist.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=max] -==== - -TIP: The unordered list marker can be changed using {uri-marker}[block styles]. - -.Ordered, basic ----- -include::{includedir}/ex-o-list.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=b-base] -==== - -NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. - -.Ordered, nested ----- -include::{includedir}/ex-o-list.adoc[tag=nest] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=nest] -==== - -.Ordered, max nesting ----- -include::{includedir}/ex-o-list.adoc[tag=max] ----- - -[.result] -==== -include::{includedir}/ex-o-list.adoc[tag=max] -==== - -TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. - -.Checklist ----- -include::{includedir}/ex-ulist.adoc[tag=check] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=check] -==== - -TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. - -.Description, single-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base] -==== - -.Description, multi-line ----- -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=b-base-multi] -==== - -.Q&A ----- -include::{includedir}/ex-dlist.adoc[tag=qa] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=qa] -==== - -.Mixed ----- -include::{includedir}/ex-dlist.adoc[tag=3-mix] ----- - -[.result] -==== -include::{includedir}/ex-dlist.adoc[tag=3-mix] -==== - -TIP: Lists can be indented. -Leading whitespace is not significant. - -.Complex content in outline lists ----- -include::{includedir}/ex-ulist.adoc[tag=b-complex] ----- - -[.result] -==== -include::{includedir}/ex-ulist.adoc[tag=b-complex] -==== - -== Links - -.External ----- -include::{includedir}/ex-url.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-base] -==== - -.With spaces and special characters ----- -include::{includedir}/ex-url.adoc[tag=b-spaces] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-spaces] -==== - -.Windows path ----- -include::{includedir}/ex-url.adoc[tag=b-windows] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-windows] -==== - -.Relative ----- -link:index.html[Docs] ----- - -[.result] -==== -link:index.html[Docs] -==== - -.Email and IRC ----- -include::{includedir}/ex-url.adoc[tag=b-scheme] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-scheme] -==== - -.Link with attributes (Asciidoctor only) ----- -include::{includedir}/ex-url.adoc[tag=b-linkattrs] ----- - -[.result] -==== -include::{includedir}/ex-url.adoc[tag=b-linkattrs] -==== - -NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. -To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. -Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. -When attribute parsing is enabled, you must quote the link text if it contains a comma. - -.Inline anchors ----- -include::{includedir}/ex-xref.adoc[tag=anchor] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=anchor] -==== - -.Internal cross references ----- -include::{includedir}/ex-xref.adoc[tag=b-base] ----- - -[.result] -==== -include::{includedir}/ex-xref.adoc[tag=b-base] -==== - -.Inter-document cross references (Asciidoctor only) ----- -include::{includedir}/ex-xref.adoc[tag=b-inter] ----- - -== Images - -Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. -You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. - -The `imagesdir` attribute can be an absolute path, relative path, or base URL. -When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. - -.Block ----- -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=base] - -include::{includedir}/ex-image.adoc[tag=alt] - -include::{includedir}/ex-image.adoc[tag=attr] - -include::{includedir}/ex-image.adoc[tag=ab-url] -==== - -.Inline ----- -include::{includedir}/ex-image.adoc[tag=in] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in] -==== - -IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. -(All macros follow this pattern). -You use an inline image when you need to place the image in a line of text. -Otherwise, you should prefer the block form. - -.Inline image with positioning role ----- -include::{includedir}/ex-image.adoc[tag=in-role] ----- - -[.result] -==== -include::{includedir}/ex-image.adoc[tag=in-role] -==== - -TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. - -.Embedded ----- -include::{includedir}/ex-image.adoc[tag=data] ----- - -NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. - -TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. - -== Videos - -.Block ----- -include::{includedir}/ex-video.adoc[tag=base] - -include::{includedir}/ex-video.adoc[tag=attr] ----- - -.Embedded Youtube video ----- -include::{includedir}/ex-video.adoc[tag=you] ----- - -.Embedded Vimeo video ----- -include::{includedir}/ex-video.adoc[tag=vim] ----- - -TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. - -== Source Code - -.Inline (monospace only) ----- -include::{includedir}/ex-text.adoc[tag=b-mono-code] ----- - -[.result] -==== -include::{includedir}/ex-text.adoc[tag=b-mono-code] -==== - -.Inline (literal) ----- -include::{includedir}/ex-pass.adoc[tag=backtick-plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=backtick-plus] -==== - -.Literal line ----- -include::{includedir}/ex-literal.adoc[tag=b-imp-code] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-imp-code] -==== - -.Literal block ----- -include::{includedir}/ex-literal.adoc[tag=b-block] ----- - -[.result] -==== -include::{includedir}/ex-literal.adoc[tag=b-block] -==== - -[listing] -.Listing block with title, no syntax highlighting -.... -include::{includedir}/ex-listing.adoc[tag=b-base] -.... - -[.result] -==== -include::{includedir}/ex-listing.adoc[tag=b-base] -==== - -[listing] -.Code block with title and syntax highlighting -.... -include::{includedir}/ex-src.adoc[tag=src-base] -.... - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-base] -==== - -[listing,subs=specialchars] -.Code block with callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-src] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-src] -==== - -[listing,subs=specialchars] -.Code block with non-selectable callouts -.... -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=b-nonselect] -==== - -[listing,subs=specialchars] -.XML code block with a non-selectable callout -.... -include::{includedir}/ex-callout.adoc[tag=source-xml] -.... - -[.result] -==== -include::{includedir}/ex-callout.adoc[tag=source-xml] -==== - -[listing] -.Code block sourced from file -.... -include::{includedir}/ex-src.adoc[tag=src-inc] -.... - -[listing] -.Code block sourced from file relative to source directory -.... -include::{includedir}/ex-src.adoc[tag=rel] -.... - -[listing] -.Strip leading indentation from source -.... -include::{includedir}/ex-src.adoc[tag=ind] -.... - -[NOTE] -==== -* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). -* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. -==== - -.Code block without delimiters (no blank lines) ----- -include::{includedir}/ex-src.adoc[tag=src-para] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=src-para] -==== - -[IMPORTANT] -.Enabling the syntax highlighter -==== -Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. - - :source-highlighter: pygments - -The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. -==== - -== More Delimited Blocks - -.Sidebar ----- -include::{includedir}/ex-sidebar.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-sidebar.adoc[tag=base] -==== - -NOTE: Any block can have a title, positioned above the block. -A block title is a line of text that starts with a dot. -The dot cannot be followed by a space. - -.Example ----- -include::{includedir}/ex-example.adoc[tag=base] ----- - -[example.result] --- -include::{includedir}/ex-example.adoc[tag=base] --- - -[#admon-bl] -.Admonition ----- -include::{includedir}/ex-admon.adoc[tag=b-bl] ----- - -[.result] -===== -include::{includedir}/ex-admon.adoc[tag=b-bl] -===== - -[TIP] -.Admonition and callout icons -==== -Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. - -To use this feature, set the value of the `icons` document attribute to `font`. -Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. - -Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. -==== - -.Blockquote ----- -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=bl] - -include::{includedir}/ex-quote.adoc[tag=para] - -include::{includedir}/ex-quote.adoc[tag=no-cite] - -include::{includedir}/ex-quote.adoc[tag=link-text] -==== - -.Abbreviated blockquote (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=abbr] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=abbr] -==== - -.Air quotes: the best thing since fenced code blocks (Asciidoctor only) ----- -include::{includedir}/ex-quote.adoc[tag=air] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=air] -==== - -.Passthrough ----- -include::{includedir}/ex-pass.adoc[tag=b-bl] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-bl] -==== - -.Open ----- -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] ----- - -[.result] -==== -include::{includedir}/ex-open.adoc[tag=base] - -include::{includedir}/ex-open.adoc[tag=src] -==== - -[listing] -.Custom substitutions -.... -include::{includedir}/ex-listing.adoc[tag=subs] -.... - -[.result] -==== -// the attribute value is hard-coded in this result since the example depends -// on a hypothetical document attribute -include::{includedir}/ex-listing.adoc[tag=subs-out] -==== - -== Block Id, Role and Options - -.Traditional (longhand) markup method for assigning block id and role ----- -[[goals]] -[role="incremental"] -* Goal 1 -* Goal 2 ----- - -.Shorthand markup method for assigning block id and role (Asciidoctor only) ----- -[#goals.incremental] -* Goal 1 -* Goal 2 ----- - -[TIP] -==== -* To specify multiple roles using the shorthand syntax, separate them by dots. -* The order of `id` and `role` values in the shorthand syntax does not matter. -==== - -.Traditional (longhand) markup method for assigning quoted text anchor (id) and role ----- -[[free_the_world]][big goal]_free the world_ ----- - -.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) ----- -[#free_the_world.big.goal]_free the world_ ----- - -.Role assigned to text enclosed in backticks ----- -[.rolename]`monospace text` ----- - -.Traditional (longhand) markup method for assigning block options ----- -[options="header,footer,autowidth"] -|=== -|Cell A |Cell B -|=== ----- - -.Shorthand markup method for assigning block options (Asciidoctor only) ----- -[%header%footer%autowidth] -|=== -|Cell A |Cell B -|=== ----- - -== Comments - -.Line ----- -include::{includedir}/ex-comment.adoc[tag=line] ----- - -TIP: Single-line comments can be used to divide elements, such as two adjacent lists. - -.Block ----- -include::{includedir}/ex-comment.adoc[tag=bl] ----- - -== Tables - -.Table with a title, three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-base-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-base-h] -==== -<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. -<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. - -.Table with two columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-h-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-h] -==== -<1> The `+*+` in the `cols` attribute is the repeat operator. -It means repeat the column specification across the remaining of columns. -In this case, we are repeating the default formatting across 2 columns. -When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. - -.Table with three columns, a header, and two rows of content ----- -include::{includedir}/ex-table.adoc[tag=b-col-indv-co] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-indv] -==== -<1> In this example, the `cols` attribute has two functions. -It specifies that this table has three columns, and it sets their relative widths. - -.Table with column containing AsciiDoc content ----- -include::{includedir}/ex-table.adoc[tag=b-col-a] ----- - -[.result] -==== -include::{includedir}/ex-table.adoc[tag=b-col-a] -==== - -.Table from CSV data ----- -include::{includedir}/ex-table-data.adoc[tag=csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=csv] -==== - -.Table from CSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-csv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-csv] -==== - -.Table from CSV data in file ----- -include::{includedir}/ex-table-data.adoc[tag=i-csv] ----- - -.Table from DSV data using shorthand (Asciidoctor only) ----- -include::{includedir}/ex-table-data.adoc[tag=s-dsv] ----- - -[.result] -==== -include::{includedir}/ex-table-data.adoc[tag=s-dsv] -==== - -.Table with formatted, aligned and merged cells ----- -include::{includedir}/ex-table-cell.adoc[tag=b-spec] ----- - -[.result] -==== -include::{includedir}/ex-table-cell.adoc[tag=b-spec] -==== - -== UI Macros - -IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. - -.Keyboard shortcuts (inline kbd macro) ----- -include::{includedir}/ex-ui.adoc[tag=key] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=key] -==== - -.Menu selections (inline menu macro) ----- -include::{includedir}/ex-ui.adoc[tag=menu] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=menu] -==== - -.Buttons (inline btn macro) ----- -include::{includedir}/ex-ui.adoc[tag=button] ----- - -[.result] -==== -include::{includedir}/ex-ui.adoc[tag=button] -==== - -== Attributes and Substitutions - -.Attribute declaration and usage ----- -include::{includedir}/ex-header-attr.adoc[tag=b-attr] ----- - -[.result] -==== -// I have to use a nested doc hack here, otherwise the attributes won't resolve -[.unstyled] -|=== -a| -include::{includedir}/ex-header-attr.adoc[tag=b-attr] -|=== -==== - -.Attribute assignment precedence (highest to lowest) -- Attribute passed to the API or CLI that does not end in `@` -- Attribute defined in the document -- Attribute passed to the API or CLI that ends in `@` -- Intrinsic attribute value (default values) - -TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. - -// Table of predefined attributes for character replacements -include::{includedir}/attrs-charref.adoc[tag=table] - -// Table of environment attributes -include::{includedir}/attrs-env.adoc[tag=table] - -.Named substitutions -include::{includedir}/subs-apply.adoc[tag=group] - -.Counter attributes ----- -include::{includedir}/ex-counter.adoc[tag=base] ----- - -[.result] -==== -include::{includedir}/ex-counter.adoc[tag=base] -==== - -== Text Replacement - -// Table of text replacements performed during replacements substitution -include::{includedir}/subs-symbol-repl.adoc[] - -TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. - -== Escaping Text - -.Backslash ----- -include::{includedir}/ex-subs.adoc[tag=b-slash] ----- - -[.result] -==== -include::{includedir}/ex-subs.adoc[tag=b-slash] -==== - -.Passthrough ("`plus for passthrough`") ----- -include::{includedir}/ex-pass.adoc[tag=plus] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=plus] -==== - -//// -.Double dollar ----- -include::{includedir}/ex-pass.adoc[tag=b-dollar] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-dollar] -==== -//// - -.Raw (triple plus and inline pass macro) ----- -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-3p-macro] -==== - -//// -.Backticks ----- -include::{includedir}/ex-pass.adoc[tag=b-tick] ----- - -[.result] -==== -include::{includedir}/ex-pass.adoc[tag=b-tick] -==== -//// - -== Table of Contents (ToC) - -.Document with ToC ----- -include::{includedir}/ex-toc.adoc[tag=base] ----- - -.Document with ToC positioned on the right ----- -include::{includedir}/ex-toc.adoc[tag=pos] ----- - -TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. - -== Bibliography - -.Bibliography with inbound references ----- -include::{includedir}/ex-biblio.adoc[tag=base] ----- - -[.result] -==== -|=== -a| -include::{includedir}/ex-biblio.adoc[tag=base] -|=== -==== - -[#section-footnotes] -== Footnotes - -.Normal and reusable footnotes ----- -include::{includedir}/ex-footnote.adoc[tag=base] ----- - -[.result] -==== -[.unstyled] -|=== -a| -include::{includedir}/ex-footnote.adoc[tag=base] -|=== -==== - -[#markdown-compatibility] -== Markdown Compatibility - -Markdown compatible syntax is only available when using Asciidoctor. - -.Markdown-style headings ----- -include::{includedir}/ex-section.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-section.adoc[tag=b-md] -==== - -.Fenced code block with syntax highlighting ----- -include::{includedir}/ex-src.adoc[tag=fence] ----- - -[.result] -==== -include::{includedir}/ex-src.adoc[tag=fence] -==== - -.Markdown-style blockquote ----- -include::{includedir}/ex-quote.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md] -==== - -.Markdown-style blockquote with block content ----- -include::{includedir}/ex-quote.adoc[tag=md-alt] ----- - -[.result] -==== -include::{includedir}/ex-quote.adoc[tag=md-alt] -==== - -.Markdown-style horizontal rules ----- -include::{includedir}/ex-hr.adoc[tag=md] ----- - -[.result] -==== -include::{includedir}/ex-hr.adoc[tag=md] -==== - -== User Manual and Help - -To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. -Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. - .Origin content