Commit 1d443f45 authored by Sarah White's avatar Sarah White Committed by Dan Allen
Browse files

resolves #13 migrate AsciiDoc syntax quick reference (PR #14)



* migrate AsciiDoc syntax quick reference
* revise commentary and improve examples
* use ~ to denote autowidth column
* add collapsible attribute to enable the extension to backport the collapsible block
* rewrite intro
* change URI to URL
* add note that empty block attribute list can be used to separate lists
* clarify that unordered list marker can be changed using style
* remove note about font-based and interactive checklists
* remove note about sectlinks and sectanchors
* include the term "literal monospace"
* add example of possessive monospace
* rename and reorder sections
* add custom inline role example
Co-authored-by: Dan Allen's avatarDan Allen <dan.j.allen@gmail.com>
parent dc1c3d28
......@@ -6,6 +6,7 @@ asciidoc:
source-language: asciidoc@
xrefstyle: short@
listing-caption: Example@
release-version: '2.0.12'
nav:
- modules/ROOT/nav.adoc
- modules/blocks/nav-basics.adoc
......
= AsciiDoc Syntax Quick Reference
:navtitle: Syntax Quick Reference
:description: The quick reference for common AsciiDoc document and text formatting markup.
:collapsible:
:url-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
:url-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs
:!table-frame:
:!table-grid:
////
This document is not meant to be a replacement for the documentation of the AsciiDoc language itself.
It's meant to be a helpful guide you can give to a writer to refer to while in the thick of writing.
Think of it a quick reminder of the most common syntax and scenarios.
It should not go into any depth about AsciiDoc processing or the options you can use when converting to an output format.
////
[IMPORTANT]
The examples on this page demonstrate the output produced by the built-in HTML converter.
An AsciiDoc converter is expected to produce complementary output when generating other output formats, such as PDF, EPUB, and DocBook.
== Paragraphs
.Paragraph
[#ex-normal]
----
include::text:example$text.adoc[tag=b-para]
----
.View result of <<ex-normal>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=b-para]
====
.Literal paragraph
[#ex-literal]
----
include::verbatim:example$literal.adoc[tag=qr-para]
----
.View result of <<ex-literal>>
[%collapsible.result]
====
include::verbatim:example$literal.adoc[tag=qr-para]
====
.Hard line breaks
[#ex-hardbreaks]
----
include::text:example$text.adoc[tag=hb-all]
----
.View result of <<ex-hardbreaks>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=hb-all]
====
.Lead paragraph
[#ex-lead]
----
include::text:example$text.adoc[tag=qr-lead]
----
.View result of <<ex-lead>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=qr-lead]
====
TIP: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a xref:blocks:preamble-and-lead.adoc[lead paragraph] if no role is specified on that paragraph.
== Text formatting
.Constrained bold, italic, and monospace
[#ex-constrained]
----
include::text:example$text.adoc[tag=constrained-bold-italic-mono]
----
.View result of <<ex-constrained>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=constrained-bold-italic-mono]
====
.Unconstrained bold, italic, and monospace
[#ex-unconstrained]
----
include::text:example$text.adoc[tag=unconstrained-bold-italic-mono]
----
.View result of <<ex-unconstrained>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=unconstrained-bold-italic-mono]
====
.Highlight, underline, strikethrough, and custom role
[#ex-lines]
----
include::text:example$text.adoc[tag=qr-all]
----
.View result of <<ex-lines>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=qr-all]
====
.Superscript and subscript
[#ex-sub-sup]
----
include::text:example$text.adoc[tag=b-sub-sup]
----
.View result of <<ex-sub-sup>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=b-sub-sup]
====
.Smart quotes and apostrophes
[#ex-curved]
----
include::text:example$text.adoc[tag=b-c-quote]
----
.View result of <<ex-curved>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=b-c-quote]
====
== Links
.Autolinks, URL macro, and mailto macro
[#ex-urls]
----
include::macros:example$url.adoc[tag=b-base]
include::macros:example$url.adoc[tag=b-scheme]
----
.View result of <<ex-urls>>
[%collapsible.result]
====
include::macros:example$url.adoc[tag=b-base]
include::macros:example$url.adoc[tag=b-scheme]
====
.URL macros with attributes
[#ex-linkattrs]
----
include::macros:example$url.adoc[tag=b-linkattrs]
----
.View result of <<ex-linkattrs>>
[%collapsible.result]
====
include::macros:example$url.adoc[tag=b-linkattrs]
====
IMPORTANT: The `link:` macro prefix is _not_ required when the target starts with a URL scheme like `https:`.
The URL scheme acts as an implicit macro prefix.
CAUTION: If the linked text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes.
Otherwise, the text will be cut off at the comma (and the remaining text will get pulled into the attribute parsing).
.URLs with spaces and special characters
----
include::macros:example$url.adoc[tag=b-spaces]
----
.Link to relative file
----
link:index.html[Docs]
----
.Link using a Windows UNC path
----
include::macros:example$url.adoc[tag=b-windows]
----
.Inline anchors
----
include::attributes:example$id.adoc[tag=anchor]
----
.Cross references
[#ex-xrefs]
----
include::macros:example$xref.adoc[tag=b-base]
----
.View result of <<ex-xrefs>>
[%collapsible.result]
====
include::macros:example$xref.adoc[tag=b-base]
====
.Inter-document cross references
----
include::macros:example$xref.adoc[tag=b-inter]
----
== Document header
The xref:document:header.adoc[document header] is optional.
The header may not contain blank lines and must be separated from the content by at least one blank line.
.Title
----
include::document:example$title.adoc[tag=qr-title]
----
.Title and author line
----
include::document:example$header.adoc[tag=qr-author]
----
.Title, author line, and revision line
----
include::document:example$header.adoc[tag=qr-rev]
----
IMPORTANT: You cannot have a xref:document:revision-line.adoc[revision line] without an xref:document:author-line.adoc[author line].
.Document header with attribute entries
----
include::document:example$header.adoc[tag=qr-attributes]
----
[#section-titles]
== Section titles
When the document type is `article` (the default), the document can only have one level-0 section title (`=`), which is the document title (i.e., doctitle).
.Article section levels
[#ex-article]
----
include::sections:example$section.adoc[tag=base]
----
.View result of <<ex-article>>
[%collapsible.result]
====
include::sections:example$section.adoc[tag=b-base]
====
The `book` document type can have additional level-0 section titles, which are interpreted as xref:sections:parts.adoc[parts].
The presence of at least one part implicitly makes the document a multi-part book.
.Book section levels
----
include::sections:example$section.adoc[tag=book]
----
////
xref:sections:title-links.adoc#link[sectlinks]::
When the document attribute `sectlinks` is set, section titles become self-links.
This feature allows a reader to easily bookmark the section.
xref:sections:title-links.adoc#anchor[sectanchors]::
When the document attribute `sectanchors` is set, a floating section icon anchor appears in front of the section title on hover.
This feature provides an alternate way for the reader to easily bookmark the section.
Section title anchors depend on support from the stylesheet to render properly.
////
.Discrete heading (not a section)
----
[discrete]
=== I'm an independent heading!
----
== Automatic TOC
.Activate Table of Contents for a document
----
= Document Title
Doc Writer <doc.writer@email.org>
:toc:
----
The Table of Content's xref:toc:title.adoc[title], xref:toc:section-depth.adoc[displayed section depth], and xref:toc:position.adoc[position] can be customized.
== Include files
.Include document parts
----
include::directives:example$include.adoc[tag=base]
----
.Include content by tagged regions or lines
----
include::directives:example$include.adoc[tag=include-with-tag]
include::directives:example$include.adoc[tag=line]
----
.Include content from a URL
----
include::directives:example$include.adoc[tag=uri]
----
WARNING: Including content from a URL 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 URL.
== Lists
.Unordered list
[#ex-ul]
----
include::lists:example$unordered.adoc[tag=qr-base]
----
.View result of <<ex-ul>>
[%collapsible.result]
====
include::lists:example$unordered.adoc[tag=qr-base]
====
TIP: A blank line is required before and after a list to separated it from other blocks.
You can force two adjacent lists apart by adding a blank attribute list (i.e., `[]`) above the second list or by inserting a blank line followed by a line comment after the first list.
If you use a line comment, the convention is to use `//-` to provide a hint to other authors that it's serving as a list divider.
.Unordered list max level nesting
[#ex-ul-max]
----
include::lists:example$unordered.adoc[tag=max]
----
.View result of <<ex-ul-max>>
[%collapsible.result]
====
include::lists:example$unordered.adoc[tag=max]
====
The xref:lists:unordered.adoc#markers[unordered list marker] can be changed using a list style (e.g., `square`).
.Ordered list
[#ex-ol]
----
include::lists:example$ordered.adoc[tag=nest]
----
.View result of <<ex-ol>>
[%collapsible.result]
====
include::lists:example$ordered.adoc[tag=nest]
====
.Ordered list max level nesting
[#ex-ol-max]
----
include::lists:example$ordered.adoc[tag=max]
----
.View result of <<ex-ol-max>>
[%collapsible.result]
====
include::lists:example$ordered.adoc[tag=max]
====
Ordered lists support xref:lists:ordered.adoc#styles[numeration styles] such as `lowergreek` and `decimal-leading-zero`.
.Checklist
[#ex-check]
----
include::lists:example$checklist.adoc[tag=check]
----
.View result of <<ex-check>>
[%collapsible.result]
====
include::lists:example$checklist.adoc[tag=check]
====
.Description list
[#ex-dlist]
----
include::lists:example$description.adoc[tag=qr-base]
----
.View result of <<ex-dlist>>
[%collapsible.result]
====
include::lists:example$description.adoc[tag=qr-base]
====
.Question and answer list
[#ex-qa]
----
include::lists:example$description.adoc[tag=qa]
----
.View result of <<ex-qa>>
[%collapsible.result]
====
include::lists:example$description.adoc[tag=qa]
====
.Mixed
[#ex-mixed]
----
include::lists:example$description.adoc[tag=3-mix]
----
.View result of <<ex-mixed>>
[%collapsible.result]
====
include::lists:example$description.adoc[tag=3-mix]
====
TIP: Lists can be indented.
Leading whitespace is not significant.
.Complex content in outline lists
[#ex-complex]
----
include::lists:example$complex.adoc[tag=b-complex]
----
.View result of <<ex-complex>>
[%collapsible.result]
====
include::lists:example$complex.adoc[tag=b-complex]
====
== Images
You can use the xref:macros:images-directory.adoc[imagesdir attribute] to avoid hard coding the common path to your images in every image macro.
The value of this attribute can be an absolute path, relative path, or base URL.
If the image target is a relative path, the attribute's value is prepended (i.e., it's resolved relative to the value of the `imagesdir` attribute).
If the image target is a URL or absolute path, the attribute's value is _not_ prepended.
.Block image macro
[#ex-image-blocks]
----
include::macros:example$image.adoc[tag=base]
include::macros:example$image.adoc[tag=alt]
include::macros:example$image.adoc[tag=attr]
include::macros:example$image.adoc[tag=ab-url]
----
.View result of <<ex-image-blocks>>
[%collapsible.result]
====
include::macros:example$image.adoc[tag=qr-base]
include::macros:example$image.adoc[tag=qr-alt]
include::macros:example$image.adoc[tag=qr-attr]
include::macros:example$image.adoc[tag=ab-url]
====
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 macro
[#ex-image-inline]
----
include::macros:example$image.adoc[tag=inline]
----
.View result of <<ex-image-inline>>
[%collapsible.result]
====
include::macros:example$image.adoc[tag=qr-inline]
====
.Inline image macro with positioning role
[#ex-image-role]
----
include::macros:example$image.adoc[tag=in-role]
----
.View result of <<ex-image-role>>
[%collapsible.result]
====
include::macros:example$image.adoc[tag=qr-role]
====
.Embedded
----
include::macros:example$image.adoc[tag=data]
----
When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {url-data-uri}[data URIs].
You can also pass it as a command line argument using `-a data-uri`.
== Videos
.Block video macro
----
include::macros:example$video.adoc[tag=base]
include::macros:example$video.adoc[tag=attr]
----
.Embedded YouTube video
----
include::macros:example$video.adoc[tag=you]
----
.Embedded Vimeo video
----
include::macros:example$video.adoc[tag=vim]
----
You can control the video settings using xref:macros:audio-and-video.adoc[additional attributes and options] on the macro.
== Keyboard, button, and menu macros
IMPORTANT: You must set the `experimental` attribute in the document header to enable these macros.
.Keyboard macro
[#ex-kbd]
----
include::macros:example$ui.adoc[tag=qr-key]
----
.View result of <<ex-kbd>>
[%collapsible.result]
====
include::macros:example$ui.adoc[tag=qr-key]
====
.Menu macro
[#ex-menu]
----
include::macros:example$ui.adoc[tag=menu]
----
.View result of <<ex-menu>>
[%collapsible.result]
====
include::macros:example$ui.adoc[tag=menu]
====
.Button macro
[#ex-button]
----
include::macros:example$ui.adoc[tag=button]
----
.View result of <<ex-button>>
[%collapsible.result]
====
include::macros:example$ui.adoc[tag=button]
====
== Literals and Source Code
////
.Inline monospace only
[#ex-inline-code]
----
include::text:example$text.adoc[tag=b-mono-code]
----
.View result of <<ex-inline-code>>
[%collapsible.result]
====
include::text:example$text.adoc[tag=b-mono-code]
====
////
.Inline literal monospace
[#ex-inline-literal]
----
include::pass:example$pass.adoc[tag=backtick-plus]
----
.View result of <<ex-inline-literal>>
[%collapsible.result]
====
include::pass:example$pass.adoc[tag=backtick-plus]
====
.Literal paragraph
[#ex-literal-line]
----
include::verbatim:example$literal.adoc[tag=b-imp-code]
----
.View result of <<ex-literal-line>>
[%collapsible.result]
====
include::verbatim:example$literal.adoc[tag=b-imp-code]
====
.Literal block
[#ex-literal-block]
----
include::verbatim:example$literal.adoc[tag=b-block]
----
.View result of <<ex-literal-block>>
[%collapsible.result]
====
include::verbatim:example$literal.adoc[tag=b-block]
====
.Listing block with title
[#ex-listing]
------
include::verbatim:example$listing.adoc[tag=qr-listing]
------
.View result of <<ex-listing>>
[%collapsible.result]
====
[caption="Listing 1. "]
include::verbatim:example$listing.adoc[tag=qr-listing]
====
.Source block with title and syntax highlighting
[#ex-highlight]
------