AsciiDoc is a mature, lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. This guide is a quick reference for the common formatting markup and document elements in the AsciiDoc syntax.
|
Note
|
Several examples focus on the output generated by the HTML backend. AsciiDoc produces complementary output when generating DocBook. Most features labeled “Asciidoctor only” can be made available to the native AsciiDoc processor by using this AsciiDoc configuration file from the Asciidoctor project. |
Paragraphs don't require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text. To begin a new paragraph, separate it by at least one blank line.
Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.
To begin a new paragraph, separate it by at least one blank line.
To preserve a line break, end the line in a space followed by a plus sign. + This results in a visible line break (e.g., `<br>`) between the lines.
To preserve a line break, end the line in a space followed by a plus sign.
This results in a visible line break (e.g., <br>) between the lines.
A normal paragraph. A sequence of lines that begin with at least one space is a literal paragraph. Literal paragraphs are treated as preformatted text. The text is shown in a fixed-width font and endlines are preserved. Another normal paragraph.
A normal paragraph.
A sequence of lines that begin with at least one space is a literal paragraph. Literal paragraphs are treated as preformatted text. The text is shown in a fixed-width font and endlines are preserved.
Another normal paragraph.
NOTE: An admonition paragraph draws the reader's attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph. Here are the other built-in admonition types: TIP: Pro tip... IMPORTANT: Don't forget... WARNING: Watch out for... CAUTION: Ensure that...
|
Note
|
An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph. |
Here are the other built-in admonition types:
|
Tip
|
Pro tip… |
|
Important
|
Don’t forget… |
|
Warning
|
Watch out for… |
|
Caution
|
Ensure that… |
|
Note
|
You can also create admonition blocks. |
[.lead] This text will be styled as a lead paragraph (i.e., larger font).
This text will be styled as a lead paragraph (i.e., larger font).
|
Note
|
The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. |
See these sections in the Asciidoctor User Manual for more information and examples.
_italic phrase_ __i__talic le__tt__ers *bold phrase* **b**old le**tt**ers *_bold italic phrase_* **__b__**old italic le**__tt__**ers `monospace phrase` and le``tt``ers `_monospace italic phrase_` and le``__tt__``ers `*monospace bold phrase*` and le``**tt**``ers `*_monospace bold italic phrase_*` and le``**__tt__**``ers `+inline literal passthrough+` (monospace text without substitutions)
italic phrase
italic letters
bold phrase
bold letters
bold italic phrase
bold italic letters
monospace phrase and letters
monospace italic phrase and letters
monospace bold phrase and letters
monospace bold italic phrase and letters
inline literal passthrough (monospace text without substitutions)
Do werewolves believe in [small]#small print#? [big]##O##nce upon an infinite loop.
Do werewolves believe in small print?
Once upon an infinite loop.
^super^script phrase ~sub~script phrase
superscript phrase
subscript phrase
'`single smart quotes`' "`double smart quotes`"
‘single smart quotes’
“double smart quotes”
See these sections in the Asciidoctor User Manual for more information and examples.
|
Important
|
A header is optional. When you do add a header to your document, the only required element is a title. |
|
Caution
|
The header may not contain blank lines and must be offset from the content by at least one blank line. |
----//toc::[]
My document provides…
.Title and author line
Doc Writer <[email protected]>
My document provides…
.Title, author line and revision line
Doc Writer <[email protected]> v1.0, 2014-01-01
My document provides…
IMPORTANT: You cannot have a revision line without an author line. .Document header with attributes
Doc Writer <[email protected]> v1.0, 2014-01-01 :toc: :imagesdir: assets/images :homepage: http://asciidoctor.org
My document provides…
[[section-titles]] == Section Titles (Headers) .Article doctype
[.result] ==== // float is required to create plain headers [float] = Document Title (Level 0) [float] == Section Level 1 [float] === Section Level 2 [float] ==== Section Level 3 [float] ===== Section Level 4 [float] ====== Section Level 5 ==== 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 `<h2>` heading. .Book doctype
[.result] ==== // float is required to create plain headers [float] = Document Title (Level 0) [float] == Section Level 1 [float] === Section Level 2 [float] ==== Section Level 3 [float] ===== Section Level 4 [float] ====== Section Level 5 [float] = Section Level 0 ==== //// 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 http://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
.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 links. NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. == Include Files .Document parts
Lead Developer
This is documentation for project X.
include::basics.adoc[]
include::installation.adoc[]
include::example.adoc[]
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
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. == Horizontal Rules and Page Breaks .Horizontal rule
[.result] ==== ''' ==== .Page break
== Lists .Unordered, basic
-
Edgar Allen Poe
-
Sheri S. Tepper
-
Bill Bryson
-
Kevin Spacey
-
Jeremy Piven
[.result] ==== * Edgar Allen Poe * Sheri S. Tepper * Bill Bryson //^ * Kevin Spacey * Jeremy Piven ==== NOTE: Blank lines are required before and after a list. TIP: You can force two lists apart with a line comment, as the previous example demonstrates. The text in the comment, (`^`), is optional, but serves as a hint to other authors that this line serves as an "end of list" marker. //toc::[] .Unordered, max nesting
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
[.result]
====
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
====
TIP: The unordered list marker can be changed using {list-marker}[block styles].
.Checklist
-
✓ checked
-
✓ also checked
-
❏ not checked
-
normal list item
[.result]
====
- [*] checked
- [x] also checked
- [ ] not checked
- normal list item
====
TIP: Checklists can use {checklist-ref}[font-based icons and be interactive].
.Ordered, basic
-
Step 1
-
Step 2
-
Step 3
[.result] ==== . Step 1 . Step 2 . Step 3 ==== .Ordered, nested
-
Step 1
-
Step 2
-
Step 2a
-
Step 2b
-
-
Step 3
[.result] ==== . Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3 ==== .Ordered, max nesting
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
[.result]
====
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
====
TIP: For ordered lists, Asciidoctor supports {list-number}[numeration styles] such as `lowergreek` and `decimal-leading-zero`.
.Labeled, single-line
- first term
-
definition of first term
- section term
-
definition of second term
[.result] ==== first term:: definition of first term section term:: definition of second term ====//toc::[] .Labeled, multi-line
- first term
-
definition of first term
- section term
-
definition of second term
[.result] ==== first term:: definition of first term section term:: definition of second term ==== .Q&A
-
What is Asciidoctor?
An implementation of the AsciiDoc processor in Ruby.
-
What is the answer to the Ultimate Question?
42
[.result] ==== [qanda] What is Asciidoctor?:: An implementation of the AsciiDoc processor in Ruby. What is the answer to the Ultimate Question?:: 42 ==== .Mixed
- Operating Systems
-
- Linux
-
-
Fedora
-
Desktop
-
-
Ubuntu
-
Desktop
-
Server
-
-
- BSD
-
-
FreeBSD
-
NetBSD
-
- Cloud Providers
-
- PaaS
-
-
OpenShift
-
CloudBees
-
- IaaS
-
-
Amazon EC2
-
Rackspace
-
[.result]
====
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
====
TIP: Lists can be indented.
Leading whitespace is not significant.
.Complex content in outline lists
-
Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.
Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.
- list continuation
-
a plus sign (+) on a line by itself
-
A literal paragraph does not require a list continuation.
$ gem install asciidoctor
-
AsciiDoc lists may contain any complex content.
Application Language AsciiDoc
Python
Asciidoctor
Ruby
[.result] ==== * Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent. + Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks. + list continuation:: a plus sign (+) on a line by itself * A literal paragraph does not require a list continuation. $ gem install asciidoctor * AsciiDoc lists may contain any complex content. + [cols="2", options="header"] |=== |Application |Language |AsciiDoc |Python |Asciidoctor |Ruby |=== ==== == Links .External
http://asciidoctor.org - automatic!
[.result] ==== http://asciidoctor.org - automatic! http://asciidoctor.org[Asciidoctor] https://github.com/asciidoctor[Asciidoctor @ *GitHub*] ==== .Relative
[.result] ==== link:index.html[Docs] ==== .Email and IRC
irc://irc.freenode.org/#asciidoctor
[.result] ==== [email protected] mailto:[email protected][Discuss Arquillian] mailto:[email protected][Subscribe, Subscribe me, I want to join!] irc://irc.freenode.org/#asciidoctor ==== .Link with attributes (Asciidoctor only)
[.result] ==== http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"] http://discuss.asciidoctor.org[Discuss Asciidoctor^] http://search.example.com["Google, Yahoo, Bing^", role="teal"] ==== NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. To enable them, you must set the `linkattrs` attribute on the document. When they are enabled, you must quote the link text if it contains a comma. .Inline anchors
[.result] ==== [[bookmark-a]]Inline anchors make arbitrary content referenceable. anchor:bookmark-b[]Use a cross reference to link to this location. ==== .Internal cross references
See Paragraphs to learn how to write paragraphs.
Learn how to organize the document into sections.
[.result] ==== See <<paragraphs>> to learn how to write paragraphs. Learn how to organize the document into <<section-titles,sections>>. ==== .Inter-document cross references (Asciidoctor only)
Refer to Section B for more information.
See you when you get back from Section B!
== Images .Block
[.result]
====
image::sunset.jpg[]
image::sunset.jpg[Sunset]
[[img-sunset]]
.A mountain sunset
image::sunset.jpg[Sunset, 300, 200, link="http://www.flickr.com/photos/javh/5448336655"]
image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
====
IMPORTANT: Images are resolved relative to the value of the {imagesdir-ref}[`imagesdir` document attribute], which defaults to an empty value.
The `imagesdir` attribute can be an absolute path, relative path or base URL.
If the image target is a URL or absolute path, the `imagesdir` prefix is _not_ added.
TIP: You should use the `imagesdir` attribute to avoid hard coding the shared path to your images in every image macro.
.Image macro using positioning role
What a beautiful sunset!
[.result]
====
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
====
TIP: There are a variety of attributes available to {image-attributes}[position and frame images].
.Inline
Click 
to get the party started.
Click 
when you need a break.
[.result] ==== Click image:icons/play.png[Play, title="Play"] to get the party started. Click image:icons/pause.png[title="Pause"] when you need a break. ==== .Embedded
NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as https://developer.mozilla.org/en-US/docs/data_URIs[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
.Embedded Youtube video
.Embedded Vimeo video
TIP: You can control the video settings using {video-ref}[additional attributes and options] on the macro.
== Source Code
.Inline
Reference code like types or methods inline.
[.result] ==== Reference code like `types` or `methods` inline. ==== .Literal line
Indent the line one space to insert a code snippet
[.result] ==== Indent the line one space to insert a code snippet ==== .Literal block
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual absolutely fatal: operation initiation lost in the dodecahedron of doom would you like to die again? y/n
[.result] ==== .... error: The requested operation returned error: 1954 Forbidden search for defensive operations manual absolutely fatal: operation initiation lost in the dodecahedron of doom would you like to die again? y/n .... ==== [listing] .Listing block with title, no syntax highlighting .... .Gemfile.lock
GEM remote: https://rubygems.org/ specs: asciidoctor (0.1.4)
PLATFORMS ruby
DEPENDENCIES asciidoctor (~> 0.1.4)
.... [.result] ==== .Gemfile.lock
GEM remote: https://rubygems.org/ specs: asciidoctor (0.1.4)
PLATFORMS ruby
DEPENDENCIES asciidoctor (~> 0.1.4)
==== [listing] .Code block with title and syntax highlighting .... [source,ruby] .app.rb
require 'sinatra'
get '/hi' do "Hello World!" end
.... [.result] ==== [source,ruby] .app.rb
require 'sinatra'
get '/hi' do "Hello World!" end
==== [listing, subs="specialcharacters"] .Code block with callouts .... [source,ruby]
require 'sinatra' <1>
get '/hi' do <2> "Hello World!" <3> end
<1> Library import <2> URL mapping <3> Content for response .... [.result] ==== [source,ruby]
require 'sinatra' <1>
get '/hi' do <2> "Hello World!" <3> end
<1> Library import <2> URL mapping <3> Content for response ==== [listing, subs="specialcharacters"] .Code block with non-selectable callouts ....
line of code // <1> line of code # <2> line of code ;; <3>
<1> A callout behind a line comment for C-style languages. <2> A callout behind a line comment for Ruby, Python, Perl, etc. <3> A callout behind a line comment for Clojure. .... [.result] ====
line of code // <1> line of code # <2> line of code ;; <3>
<1> A callout behind a line comment for C-style languages. <2> A callout behind a line comment for Ruby, Python, Perl, etc. <3> A callout behind a line comment for Clojure. ==== [listing, subs="specialcharacters"] .XML code block with a non-selectable callout .... [source,xml]
<section> <title>Section Title</title> <!--1-→ </section>
<1> The section title is required. .... [.result] ==== [source,xml]
<section> <title>Section Title</title> <!--1-→ </section>
<1> The section title is required. ==== [listing] .Code block sourced from file .... [source,ruby]
include::app.rb[]
.... [listing] .Code block sourced from file relative to source directory .... :sourcedir: src/main/java [source,java]
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
.... [listing] .Strip leading indentation from source .... [source,ruby,indent=0]
include::lib/document.rb[lines=5..10]
.... [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)
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
----<meta name="viewport"
content="width=device-width, initial-scale=1.0">|
Important
|
Enabling the syntax highlighter
Syntax highlighting is enabled by setting the :source-highlighter: pygments The valid options for are |
.AsciiDoc history **** AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX. ****
AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX.
|
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. |
.Sample document ==== Here's a sample AsciiDoc document: [listing] .... = Title of Document Doc Writer :toc: This guide provides... .... The document header is useful, but not required. ====
Here’s a sample AsciiDoc document:
= Title of Document Doc Writer :toc: This guide provides...
The document header is useful, but not required.
[NOTE] ==== An admonition block may contain complex content. .A list - one - two - three Another paragraph. ====
|
Note
|
An admonition block may contain complex content. A list
Another paragraph. |
|
Tip
|
Admonition and callout icons
Asciidoctor can "draw" icons using Font Awesome and CSS. To use this feature, set the value of the |
[quote, Abraham Lincoln, Soldiers' National Cemetery Dedication] ____ Four score and seven years ago our fathers brought forth on this continent a new nation... ____ [quote, Albert Einstein] A person who never made a mistake never tried anything new. ____ A person who never made a mistake never tried anything new. ____
Four score and seven years ago our fathers brought forth on this continent a new nation…
Soldiers' National Cemetery Dedication
A person who never made a mistake never tried anything new.
A person who never made a mistake never tried anything new.
"I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical." -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
Papers of Thomas Jefferson: Volume 11
As a tip of the hat to Dick, Asciidoctor recognizes text between "air quotes" as a quote block. Air quotes are the best thing since fenced code blocks.
[, Richard M. Nixon] "" When the President does it, that means that it's not illegal. ""
"" When the President does it, that means that it’s not illegal. ""
++++ <p> Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist: </p> <script src="http://gist.github.com/mojavelinux/5333524.js"> </script> ++++
Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist:
-- An open block can be an anonymous container, or it can masquerade as any other block. -- [source] -- puts "I'm a source block!" --
An open block can be an anonymous container, or it can masquerade as any other block.
puts "I'm a source block!":version: 0.1.4
[source,xml]
[subs="verbatim,attributes"]
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>{version}</version>
</dependency>
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>0.1.4</version>
</dependency>id and role[[goals]] [role="incremental"] * Goal 1 * Goal 2
id and role (Asciidoctor only)[#goals.incremental] * Goal 1 * Goal 2
|
Tip
|
|
id) and role[[free_the_world]][big goal]_free the world_
id) and role (Asciidoctor only)[#free_the_world.big.goal]_free the world_
[rolename]`escaped monospace text`
options[options="header,footer,autowidth"] |=== |Cell A |Cell B |===
options (Asciidoctor only)[%header%footer%autowidth] |=== |Cell A |Cell B |===
// A single-line comment.
|
Tip
|
Single-line comments can be used to divide elements, such as two adjacent lists. |
//// A multi-line comment. Notice it's a delimited block. ////
.Table Title |=== |Name of Column 1 |Name of Column 2 |Name of Column 3 (1) (2) |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |Cell in column 3, row 2 |===
-
Unless the
colsattribute is specified, the number of columns is equal to the number of vertical bars on the first non-blank line inside the block delimiters. -
When a blank line follows a single line of column titles, the column titles row will be styled as a header row by default.
| Name of Column 1 | Name of Column 2 | Name of Column 3 |
|---|---|---|
Cell in column 1, row 1 |
Cell in column 2, row 1 |
Cell in column 3, row 1 |
Cell in column 1, row 2 |
Cell in column 2, row 2 |
Cell in column 3, row 2 |
[cols="2*", options="header"] (1) |=== |Name of Column 1 |Name of Column 2 |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |===
-
The
*in thecolsattribute is the repeat operator. It means repeat the column specification for the remainder of columns. In this case, it means to repeat the default formatting across 4 columns. When the header row is not defined on a single line, you must use thecolsattribute to set the number of columns andoptionsattributes to make the first row a header.
| Name of Column 1 | Name of Column 2 |
|---|---|
Cell in column 1, row 1 |
Cell in column 2, row 1 |
Cell in column 1, row 2 |
Cell in column 2, row 2 |
[cols="1,1,2", options="header"] (1) .Applications |=== |Name |Category |Description |Firefox |Browser |Mozilla Firefox is an open-source web browser. It's designed for standards compliance, performance, portability. |Arquillian |Testing |An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests. |===
-
In this example, the
colsattribute has two functions. It specifies that this table has three columns, and it sets their relative widths.
| Name | Category | Description |
|---|---|---|
Firefox |
Browser |
Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance, portability. |
Arquillian |
Testing |
An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests. |
[cols="2,2,5a"] |=== |Firefox |Browser |Mozilla Firefox is an open-source web browser. It's designed for: * standards compliance * performance * portability http://getfirefox.com[Get Firefox]! |===
Firefox |
Browser |
Mozilla Firefox is an open-source web browser. It’s designed for:
|
[format="csv", options="header"] |=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop The Lumineers,Ho Hey,Folk Rock |===
| Artist | Track | Genre |
|---|---|---|
Baauer |
Harlem Shake |
Hip Hop |
The Lumineers |
Ho Hey |
Folk Rock |
,=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop ,===
| Artist | Track | Genre |
|---|---|---|
Baauer |
Harlem Shake |
Hip Hop |
:=== Artist:Track:Genre Robyn:Indestructable:Dance :===
| Artist | Track | Genre |
|---|---|---|
Robyn |
Indestructable |
Dance |
[cols="e,m,^,>s", width="25%"] |=== |1 >s|2 |3 |4 ^|5 2.2+^.^|6 .3+<.>m|7 ^|8 |9 2+>|10 |===
1 |
2 |
3 |
4 |
5 |
|
|
|
8 |
|||
9 |
|
||
|
Important
|
You must set the experimental attribute in the document header to enable these macros.
|
kbd macro)|=== |Shortcut |Purpose |kbd:[F11] |Toggle fullscreen |kbd:[Ctrl+T] |Open a new tab |kbd:[Ctrl+Shift+N] |New incognito window |kbd:[Ctrl + +] |Increase zoom |===
| Shortcut | Purpose |
|---|---|
F11 |
Toggle fullscreen |
Ctrl+T |
Open a new tab |
Ctrl+Shift+N |
New incognito window |
Ctrl++ |
Increase zoom |
menu macro)To save the file, select menu:File[Save]. Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
To save the file, select File › Save.
Select View › Zoom › Reset to reset the zoom level to the default setting.
btn macro)Press the btn:[OK] button when you are finished. Select a file in the file navigator and click btn:[Open].
Press the OK button when you are finished.
Select a file in the file navigator and click Open.
:homepage: http://asciidoctor.org
:docslink: http://asciidoctor.org/docs[Asciidoctor's Docs]
:desc: Asciidoctor is a mature, plain-text document format for +
writing notes, articles, documentation, books, and more. +
It's also a text processor & toolchain for translating +
documents into various output formats (i.e., backends), +
including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[`[✔]`]
Check out {homepage}[Asciidoctor]!
{desc}
Check out {docslink} too!
{checkedbox} That's done!
Check out Asciidoctor! Asciidoctor is a mature, plain-text document format for writing notes, articles, documentation, books, and more. It’s also a text processor & toolchain for translating documents into various output formats (i.e., backends), including HTML, DocBook, PDF and ePub. Check out Asciidoctor’s Docs too!
|
-
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.
|
| Attribute reference | Replacement | Rendered |
|---|---|---|
\{lt} |
< |
< |
\{gt} |
> |
> |
\{amp} |
& |
& |
\{startsb} |
[ |
[ |
\{endsb} |
] |
] |
\{vbar} |
| |
| |
\{caret} |
^ |
^ |
\{asterisk} |
* |
* |
\{tilde} |
~ |
~ |
\{apostrophe} |
' |
' |
\{backslash} |
\ |
\ |
\{backtick} |
` |
` |
\{two-colons} |
:: |
:: |
\{two-semicolons} |
;; |
;; |
| Attribute reference | Replacement | Rendered |
|---|---|---|
\{empty} |
_nothing_ |
|
\{sp}, \{space} |
_single space_ |
|
\{nbsp} |
\  |
|
\{zwsp} |
\​ |
|
\{wj} |
\⁠ |
|
\{apos} |
\' |
' |
\{quot} |
\" |
" |
\{lsquo} |
\‘ |
‘ |
\{rsquo} |
\’ |
’ |
\{ldquo} |
\“ |
“ |
\{rdquo} |
\” |
” |
\{deg} |
\° |
° |
\{plus} |
\+ |
+ |
\{brvbar} |
\¦ |
¦ |
| Attribute | Description |
|---|---|
|
Calls the processor |
|
Version of the processor |
|
Backend used to render document |
|
Last modified date |
|
Last modified date and time |
|
Name of document directory |
|
Name of document file |
|
Last modified time |
|
The title of the document |
|
Document’s doctype (e.g., article) |
|
Local date when rendered |
|
Local date and time when rendered |
|
Local time when rendered |
none
|
Disables substitutions |
normal
|
Performs all substitutions except for callouts |
verbatim
|
Replaces special characters and processes callouts |
specialcharacters
|
Replaces |
quotes
|
Applies text formatting |
attributes
|
Replaces attribute references |
replacements
|
Substitutes textual and character reference replacements |
macros
|
Processes macros |
post_replacements
|
Replaces the line break character ( |
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description
|PX-{counter:index}
|Description of PX-{index}
|PX-{counter:index}
|Description of PX-{index}
|===
| Part Id | Description |
|---|---|
PX-1 |
Description of PX-1 |
PX-2 |
Description of PX-2 |
| Name | Syntax | Unicode Replacement | Rendered | Notes |
|---|---|---|---|---|
Copyright |
\(C) |
\© |
© |
|
Registered |
\(R) |
\® |
® |
|
Trademark |
\(TM) |
\™ |
™ |
|
Em dash |
\-- |
\— |
— |
When space is detected on either side of the em dash, the thin space numeric character entity ( |
ellipses |
\... |
\… |
… |
|
right single arrow |
\-> |
\→ |
→ |
|
right double arrow |
\=> |
\⇒ |
⇒ |
|
left single arrow |
\<- |
\← |
← |
|
left double arrow |
\<= |
\⇐ |
⇐ |
|
apostrophe |
Sam\'s |
Sam\’s |
Sam’s |
The vertical form apostrophe is replaced with the curved form apostrophe. |
|
Tip
|
Any named, numeric or hex XML entity reference is supported. |
\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.
\{author} is not resolved to the author name.
The curly brackets around the word are preserved.
The backslash character is automatically removed.
*Stars* is not rendered as bold text. The asterisks around the word are preserved.
{author} is not resolved to the author name. The curly brackets around the word are preserved.
The backslash character is automatically removed.
$$*Stars*$$ is not rendered as bold text. The asterisks around the word are preserved. $$&$$ renders as an XML entity instead of &.
*Stars* is not rendered as bold text. The asterisks around the word are preserved.
& renders as an XML entity instead of &.
+++<u>underline me</u>+++ renders as underlined text. pass:[<u>underline me</u>] also renders as underlined text.
underline me renders as underlined text.
underline me also renders as underlined text.
`Text in {backticks}` renders exactly as entered, in `monospace`.
The attribute reference is not resolved.
Text in {backticks} renders exactly as entered, in monospace.
The attribute reference is not resolved.
= AsciiDoc Writer's Guide Doc Writer <[email protected]> v1.0, 2013-01-01 :toc:
= AsciiDoc Writer's Guide Doc Writer <[email protected]> v1.0, 2013-01-01 :toc: right
|
Tip
|
The ToC "title, levels, and positioning" can be customized. |
'The Pragmatic Programmer' <<prag>> should be required reading for all developers. [bibliography] - [[[prag]]] Andy Hunt & Dave Thomas. 'The Pragmatic Programmer: From Journeyman to Master'. Addison-Wesley. 1999. - [[[seam]]] Dan Allen. 'Seam in Action'. Manning Publications. 2008.
'The Pragmatic Programmer' [prag] should be required reading for all developers.
A statement.footnote:[Clarification about this statement.] A bold statement.footnoteref:[disclaimer,These opinions are my own.] Another bold statement.footenoteref:[disclaimer]
|
Important
|
Markdown compatibility is only available by default in Asciidoctor. You can configure AsciiDoc (Python) to recognize this syntax by putting the AsciiDoc compatibility file from Asciidoctor in the same directory as the document being processed. |
# Document Title (Level 0) ## Section Level 1 ### Section Level 2 #### Section Level 3 ##### Section Level 4 ###### Section Level 5
```ruby require 'sinatra' get '/hi' do "Hello World!" end ```
require 'sinatra'
get '/hi' do
"Hello World!"
end> I hold it that a little rebellion now and then is a good thing, > and as necessary in the political world as storms in the physical. > -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
Papers of Thomas Jefferson: Volume 11
> > What's new? > > I've got Markdown in my AsciiDoc! > > > Like what? > > * Blockquotes > * Headings > * Fenced code blocks > > > Is there more? > > Yep. AsciiDoc and Markdown share a lot of common syntax already.
What’s new?
I’ve got Markdown in my AsciiDoc!
Like what?
Blockquotes
Headings
Fenced code blocks
Is there more?
Yep. AsciiDoc and Markdown share a lot of common syntax already.
--- - - - *** * * *
To learn more about Asciidoctor and its capabilities, check out the other Asciidoctor guides and its User Manual. Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.