= AsciiDoc Syntax :icons: font :stem: :toc: left :url-docs: https://asciidoctor.org/docs :url-gem: https://rubygems.org/gems/asciidoctor A brief reference of the most commonly used AsciiDoc syntax. You can find the full documentation for the AsciiDoc syntax at {url-docs}. == Paragraphs A normal paragraph. Line breaks are not preserved. // line comments, which are lines that start with //, are skipped A blank line separates paragraphs. [%hardbreaks] This paragraph is marked with the `hardbreaks` option. Notice how line breaks are now preserved. An indented (literal) paragraph disables text formatting, preserves spaces and line breaks, and is displayed in a monospaced font. [sidebar#id.role] Adding a style, ID, and/or role gives a paragraph (or block) special meaning, like this sidebar. NOTE: An admonition paragraph, like this note, grabs the reader's attention. TIP: Convert this document using the `asciidoctor` command to see the output produced from it. == Text Formatting :hardbreaks-option: .Constrained (applied at word boundaries) *strong importance* (aka bold) _stress emphasis_ (aka italic) `monospaced` (aka typewriter text) "`double`" and '`single`' typographic quotes +passthrough text+ (substitutions disabled) `+literal text+` (monospaced with substitutions disabled) a #mark# to remember (highlighted for notation) .Unconstrained (applied anywhere) **C**reate, **R**ead, **U**pdate, and **D**elete (CRUD) fan__freakin__tastic ``mono``culture ##mark##up your text .Replacements A long time ago in a galaxy far, far away... (C) 1976 Arty Artisan I believe I shall--no, actually I won't. .ID and roles for phrases [.line-through]#delete me# the [.path]_images_ directory a [#wibble.term]*wibble* does wobble .Macros // where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc. The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow]. The pass:c[->] operator is often referred to as the stabby lambda. Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}]. // activate stem support by adding `:stem:` to the document header stem:[sqrt(4) = 2] :!hardbreaks-option: == Attributes // define attributes in the document header; must be flush with left margin :name: value You can download and install Asciidoctor {asciidoctor-version} from {url-gem}. C{pp} is not required, only Ruby. Use a leading backslash to output a word enclosed in curly braces, like \{name}. == Links [%hardbreaks] https://example.org/page[A webpage] link:../path/to/file.txt[A local file] xref:document.adoc[A sibling document] mailto:hello@example.org[Email to say hello!] == Anchors [[idname,reference text]] // or written using normal block attributes as `[#idname,reftext=reference text]` A paragraph (or any block) with an anchor (aka ID) and reftext. See <> or <>. xref:document.adoc#idname[Jumps to anchor in another document]. This paragraph has a footnote.footnote:[This is the text of the footnote.] == Lists === Unordered * level 1 ** level 2 *** level 3 **** level 4 ***** etc. * back at level 1 + Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block). .Some Authors [circle] - Edgar Allen Poe - Sheri S. Tepper - Bill Bryson === Ordered . Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3 .Remember your Roman numerals? [upperroman] . is one . is two . is three === Checklist * [x] checked * [ ] not checked === Callout // enable callout bubbles by adding `:icons: font` to the document header [,ruby] ---- puts 'Hello, World!' # <1> ---- <1> Prints `Hello, World!` to the console. === Description first term:: description of first term second term:: description of second term == Document Structure === Header // header must be flush with left margin = Document Title Author Name v1.0, 2019-01-01 === Sections // must be flush with left margin = Document Title (Level 0) == Level 1 === Level 2 ==== Level 3 ===== Level 4 ====== Level 5 == Back at Level 1 === Includes // must be flush with left margin include::basics.adoc[] // define -a allow-uri-read to allow content to be read from URI include::https://example.org/installation.adoc[] == Blocks -- open - a general-purpose content wrapper; useful for enclosing content to attach to a list item -- // recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING // enable admonition icons by setting `:icons: font` in the document header [NOTE] ==== admonition - a notice for the reader, ranging in severity from a tip to an alert ==== ==== example - a demonstration of the concept being documented ==== .Toggle Me [%collapsible] ==== collapsible - these details are revealed by clicking the title ==== **** sidebar - auxiliary content that can be read independently of the main content **** .... literal - an exhibit that features program output .... ---- listing - an exhibit that features program input, source code, or the contents of a file ---- [,language] ---- source - a listing that is embellished with (colorized) syntax highlighting ---- ```language fenced code - a shorthand syntax for the source block ``` [,attribution,citetitle] ____ quote - a quotation or excerpt; attribution with title of source are optional ____ [verse,attribution,citetitle] ____ verse - a literary excerpt, often a poem; attribution with title of source are optional ____ ++++ pass - content passed directly to the output document; often raw HTML ++++ // activate stem support by adding `:stem:` to the document header [stem] ++++ x = y^2 ++++ //// comment - content which is not included in the output document //// == Tables .Table Attributes [cols=>1h;2d,width=50%,frame=ends] |=== | Attribute Name | Values | options | header,footer,autowidth | cols | colspec[;colspec;...] | grid | all \| cols \| rows \| none | frame | all \| sides \| ends \| none | stripes | all \| even \| odd \| none | width | (0%..100%) | format | psv {vbar} csv {vbar} dsv |=== == Multimedia image::screenshot.png[block image,800,450] Press image:reload.svg[reload,16,opts=interactive] to reload the page. video::movie.mp4[width=640,start=60,end=140,options=autoplay] video::aHjpOzsQ9YI[youtube] video::300817511[vimeo] == Breaks // thematic break (aka horizontal rule) --- // page break <<<