Build a Basic Block

Delimited blocks

Block content can be styled by enclosing it in a pair of delimiters (i.e., delimiter lines). A delimited block has an opening delimiter and a closing delimiter. The opening and closing delimiters must be the same length. The style and substitutions applied to the delimited block’s content is indicated by the characters in the delimiters.

Build a block using delimiters

In this section, we’ll create a delimited sidebar block. The delimiter for the sidebar style is four asterisks (****).

  1. Enter the opening delimiter at the beginning of a new line and then press Enter.

    Text in your document.

****

  2. On the new line, enter your content, such as paragraphs, delimited blocks, directives, and macros. The delimited block’s style will be applied to all of this content until the closing delimiter.

    Text in your document.

****
This is content in a sidebar block.

image::name.png[]

This is more content in the sidebar block.

  3. To end the delimited block, press Enter at the end of your last line of content. On the new line, type the closing delimiter.

    Text in your document.

****
This is content in a sidebar block.

image::name.png[]

This is more content in the sidebar block.
****

That’s it. You’ve built a delimited block.

Build a block using a block style attribute

In some cases, you can style a block using the style’s name. If the content is contiguous (not interrupted by blank lines), you can assign the block style’s name in an attribute list placed above the content. This format is often used for single-line listings:

[listing]
sudo dnf install asciidoc

or single-line quotes:

[quote]
Never do today what you can put off `'til tomorrow.

Built-in block styles summary

The following table identifies the built-in block styles, their delimiter syntax, purposes, and the substitutions performed on their contents.

Block Block Name Delimiter Purpose Substitutions

Paragraph

n/a

n/a

Regular paragraph content (i.e., prose), offset on either side by a blank line. Must start flush to the left margin of the document. The block name can be used to convert the paragraph into most other blocks.

Normal

Literal paragraph

n/a

n/a

A special type of paragraph block for literal content (i.e., preformatted text). Must be indented from the left margin of the document by at least one space. Often used as a shorthand for a literal delimited block when the content does not contain any blank lines.

Verbatim

Admonition

[<LABEL>]

====

Aside content that demands special attention; often labeled with a tag or icon

Normal

Comment

n/a

////

Private notes that are not displayed in the output

None

Example

[example]

====

Designates example content or defines an admonition block

Normal

Fenced

n/a

```

Source code or keyboard input is displayed as entered. Will be colorized by the source highlighter if enabled on the document and a language is set.

Verbatim

Listing

[listing]

----

Source code or keyboard input is displayed as entered

Verbatim

Literal

[literal]

....

Output text is displayed exactly as entered

Verbatim

Open

Most block names

--

Anonymous block that can act as any block except passthrough or table blocks

Varies

Passthrough

[pass]

++++

Unprocessed content that is sent directly to the output

None

Quote

[quote]

____

A quotation with optional attribution

Normal

Sidebar

[sidebar]

****

Aside text and content displayed outside the flow of the document

Normal

Source

[source]

----

Source code or keyboard input to be displayed as entered. Will be colorized by the source highlighter if enabled on the document and a language is set.

Verbatim

Stem

[stem]

++++

Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math)

None

Table

n/a

|===

Displays tabular content

Varies

Verse

[verse]

____

A verse with optional attribution

Normal