Blockquotes

Prose excerpts, quotes and verses share the same syntax structure, including:

  • block name, either quote or verse

  • name of who the content is attributed to

  • bibliographical information of the book, speech, play, poem, etc., where the content was drawn from

  • excerpt text

Basic quote syntax

For content that doesn’t require the preservation of line breaks, set the quote attribute in the first position of the attribute list. Next, set the attribution and relevant citation information. These positional attributes are all optional.

Example 1. Anatomy of a basic quote
[quote,attribution,citation title and information]
Quote or excerpt text

You can include an optional space after the comma that separates each positional attribute. If an attribute value includes a comma, enclose the value in double or single quotes.

If the quote is a single line or paragraph (i.e., a styled paragraph), you can place the attribute list directly on top of the text.

Example 2. Quote paragraph syntax
.After landing the cloaked Klingon bird of prey in Golden Gate park: (1)
[quote,Captain James T. Kirk,Star Trek IV: The Voyage Home] (2) (3) (4)
Everybody remember where we parked. (5)
1 Mark lead-in text explaining the context or setting of the quote using a period (.). (optional)
2 For content that doesn’t require the preservation of line breaks, set quote in the first position of the attribute list.
3 The second position contains who the excerpt is attributed to. (optional)
4 Enter additional citation information in the third position. (optional)
5 Enter the excerpt or quote text on the line immediately following the attribute list.

The result of Example 2 is displayed below.

After landing the cloaked Klingon bird of prey in Golden Gate park:
Everybody remember where we parked.
— Captain James T. Kirk
Star Trek IV: The Voyage Home

Quoted block

If the quote or excerpt is more than one paragraph, place the text between delimiter lines consisting of four underscores (____).

Example 3. Quote block syntax
[quote,Monty Python and the Holy Grail]
____
Dennis: Come and see the violence inherent in the system. Help! Help! I'm being repressed!

King Arthur: Bloody peasant!

Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That's what I'm on about! Did you see him repressing me? You saw him, Didn't you?
____

The result of Example 3 is displayed below.

Dennis: Come and see the violence inherent in the system. Help! Help! I’m being repressed!

King Arthur: Bloody peasant!

Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That’s what I’m on about! Did you see him repressing me? You saw him, Didn’t you?

— Monty Python and the Holy Grail

Quoted paragraph

You can turn a single paragraph into a blockquote by:

  1. surrounding it with double quotes

  2. adding an optional attribution (prefixed with two dashes) below the quoted text

Example 4. Quoted paragraph syntax
"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

The result of Example 4 is displayed below.

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

Excerpt

The quote block can be designated as an excerpt by adding the excerpt role. The exceptation is that this role makes the quote block appear with the quote decoration.

[.excerpt]
____
This text is an excerpt from the referenced literature.
____

The impact of this role is strictly a presentation concern and is thus handled by the styling system, such as the stylesheet for HTML.

Markdown-style blockquotes

Asciidoctor supports Markdown-style blockquotes. This syntax was adopted both to ease the transition from Markdown and because it’s the most common method of quoting in email messages.

Example 5. Markdown-style blockquote syntax
> 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

The result of Example 5 is displayed below.

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

Like Markdown, Asciidoctor supports some block content inside the blockquote, including paragraphs, lists, and nested blockquotes.

Example 6. Markdown-style blockquote containing block content
> > 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.

Here’s how the conversation from Example 6 is rendered.

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.

Be aware that not all AsciiDoc block elements are supported inside a Markdown-style blockquote. In particular, a description list is not permitted. The parser looks for the Markdown-style blockquote only after looking for a description list, meaning the description list takes precedence. Since the quote marker is a valid prefix for a description list term, the Markdown-style blockquote is not recognized in this case. If you need to put a description list inside a blockquote, you should use the AsciiDoc syntax for a blockquote instead.

The Markdown-style blockquote should only be used in simple cases and when migrating from Markdown. The AsciiDoc syntax should always be preferred, if possible.