---

Delimited Blocks

Delimited blocks are blocks of text enveloped by leading and trailing delimiter lines (normally a series of four or more repeated characters). The behavior of Delimited Blocks is specified by entries in configuration file [blockdef-*] sections.

Predefined Delimited Blocks

AsciiDoc ships with a number of predefined DelimitedBlocks (see the asciidoc.conf configuration file in the asciidoc(1) program directory):

Predefined delimited block underlines:

CommentBlock:     //////////////////////////
PassthroughBlock: ++++++++++++++++++++++++++
ListingBlock:     --------------------------
LiteralBlock:     ..........................
SidebarBlock:     **************************
QuoteBlock:       __________________________
ExampleBlock:     ==========================
OpenBlock:        --

	Attributes	Callouts	Macros	Quotes	Replacements	Special chars	Special words
PassthroughBlock	Yes	No	Yes	No	No	No	No
ListingBlock	No	Yes	No	No	No	Yes	No
LiteralBlock	No	Yes	No	No	No	Yes	No
SidebarBlock	Yes	No	Yes	Yes	Yes	Yes	Yes
QuoteBlock	Yes	No	Yes	Yes	Yes	Yes	Yes
ExampleBlock	Yes	No	Yes	Yes	Yes	Yes	Yes
OpenBlock	Yes	No	Yes	Yes	Yes	Yes	Yes

Table 1. Default DelimitedBlock substitutions

Listing Blocks

ListingBlocks are rendered verbatim in a monospaced font, they retain line and whitespace formatting and are often distinguished by a background or border. There is no text formatting or substitutions within Listing blocks apart from Special Characters and Callouts. Listing blocks are often used for computer output and file listings.

Here’s an example:

-------------------------------------- #include <stdio.h> int main() { printf("Hello World!\n"); exit(0); } --------------------------------------

Which will be rendered like:

#include <stdio.h> int main() { printf("Hello World!\n"); exit(0); }

By convention filter blocks use the listing block syntax and are implemented as distinct listing block styles.

Literal Blocks

LiteralBlocks are rendered just like literal paragraphs. Example:

................................... Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui. ...................................

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

If the listing style is applied to a LiteralBlock it will be rendered as a ListingBlock (this is handy if you have a listing containing a ListingBlock).

Sidebar Blocks

A sidebar is a short piece of text presented outside the narrative flow of the main text. The sidebar is normally presented inside a bordered box to set it apart from the main text.

The sidebar body is treated like a normal section body.

Here’s an example:

.An Example Sidebar ************************************************ Any AsciiDoc SectionBody element (apart from SidebarBlocks) can be placed inside a sidebar. ************************************************

Which will be rendered like:

An Example Sidebar Any AsciiDoc SectionBody element (apart from SidebarBlocks) can be placed inside a sidebar.

Comment Blocks

The contents of CommentBlocks are not processed; they are useful for annotations and for excluding new or outdated content that you don’t want displayed. CommentBlocks are never written to output files. Example:

////////////////////////////////////////// CommentBlock contents are not processed by asciidoc(1). //////////////////////////////////////////

See also Comment Lines.

Note	System macros are executed inside comment blocks.

Passthrough Blocks

By default the block contents is subject only to attributes and macros substitutions (use an explicit subs attribute to apply different substitutions). PassthroughBlock content will often be backend specific. Here’s an example:

[subs="quotes"] ++++++++++++++++++++++++++++++++++++++ <table border="1"><tr> <td>*Cell 1*</td> <td>*Cell 2*</td> </tr></table> ++++++++++++++++++++++++++++++++++++++

The following styles can be applied to passthrough blocks:

pass

No substitutions are performed. This is equivalent to subs="none".

asciimath, latexmath

By default no substitutions are performed, the contents are rendered as mathematical formulas.

Quote Blocks

QuoteBlocks are used for quoted passages of text. There are two styles: quote and verse. The style behavior is identical to quote and verse paragraphs except that blocks can contain multiple paragraphs and, in the case of the quote style, other section elements. The first positional attribute sets the style, if no attributes are specified the quote style is used. The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the quote’s author and source. For example:

[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] ____________________________________________________________________ As he spoke there was the sharp sound of horses' hoofs and grating wheels against the curb, followed by a sharp pull at the bell. Holmes whistled. "A pair, by the sound," said he. "Yes," he continued, glancing out of the window. "A nice little brougham and a pair of beauties. A hundred and fifty guineas apiece. There's money in this case, Watson, if there is nothing else." ____________________________________________________________________

Which is rendered as:

As he spoke there was the sharp sound of horses' hoofs and grating wheels against the curb, followed by a sharp pull at the bell. Holmes whistled.

"A pair, by the sound," said he. "Yes," he continued, glancing out of the window. "A nice little brougham and a pair of beauties. A hundred and fifty guineas apiece. There’s money in this case, Watson, if there is nothing else."

The Adventures of Sherlock Holmes
— Sir Arthur Conan Doyle

Example Blocks

ExampleBlocks encapsulate the DocBook Example element and are used for, well, examples. Example blocks can be titled by preceding them with a BlockTitle. DocBook toolchains will normally automatically number examples and generate a List of Examples backmatter section.

Example blocks are delimited by lines of equals characters and can contain any block elements apart from Titles, BlockTitles and Sidebars) inside an example block. For example:

.An example ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. =====================================================================

Renders:

Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens.

Example 1. An example

A title prefix that can be inserted with the caption attribute (HTML backends). For example:

[caption="Example 1: "] .An example with a custom caption ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. =====================================================================

Admonition Blocks

The ExampleBlock definition includes a set of admonition styles (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions containing more than a single paragraph). Just precede the ExampleBlock with an attribute list specifying the admonition style name. For example:

[NOTE] .A NOTE admonition block ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. . Fusce euismod commodo velit. . Vivamus fringilla mi eu lacus. .. Fusce euismod commodo velit. .. Vivamus fringilla mi eu lacus. . Donec eget arcu bibendum nunc consequat lobortis. =====================================================================

Renders:

Note	A NOTE admonition block Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis.

See also Admonition Icons and Captions.

Open Blocks

Open blocks are special:

• The open block delimiter is line containing two hyphen characters (instead of four or more repeated characters).

• They can be used to group block elements for List item continuation.

• Open blocks can be styled to behave like any other type of delimited block. The following built-in styles can be applied to open blocks: literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz. For example, the following open block and listing block are functionally identical:

  [listing]
  --
  Lorum ipsum ...
  --

  ---------------
  Lorum ipsum ...
  ---------------

• An unstyled open block groups section elements but otherwise does nothing.

Open blocks are used to generate document abstracts and book part introductions:

• Apply the abstract style to generate an abstract, for example:

  [abstract]
  --
  In this paper we will ...
  --

  1. Apply the partintro style to generate a book part introduction for a multi-part book, for example:

     [partintro]
     .Optional part introduction title
     --
     Optional part introduction goes here.
     --