Build a Basic Block

Build a delimited block

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 from a paragraph

In some cases, you can style a block using the style’s name. If the content is contiguous (not interrupted by empty lines or comment 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.

However, note that the lines of a styled paragraph are first parsed like a paragraph, then promoted to the specified block type. That means that line comments will be dropped, which can impact verbatim blocks such as a listing block. Thus, the delimited block form is preferred, especially when creating a verbatim block.

Summary of built-in blocks

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 an empty 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 empty 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