= 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 <<idname>> or <<idname,optional text of internal link>>.

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 Allan 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 <author@example.org>
 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
<<<