Building Blocks With AsciiDoc

AsciiDoc provides a way to include non-paragraph texts in your documents, such as block quotes, source code listings, sidebars, and tables. These components, known as delimited blocks, are surrounded by delimiter lines that clearly define their boundaries.

This approach helps adequately structure your documents, adding clarity, organization, and emphasis to your writing by ensuring these elements are formatted and rendered distinctly from regular text.

Delimited blocks#

Delimited blocks separate different sections within an AsciiDoc document. They allow you to define and format various types of content, such as quotes, examples, sidebars, and more. Each type of delimited block is defined by a unique set of delimiters.

Examples of Delimited Blocks

Example Blocks:#

Example blocks provide examples or additional information related to the content. They are delimited with equal signs (====) as seen below

1==== Example Block
2==== This is an example block. It can be used to illustrate a point. ====

Quote Blocks#

Quote blocks are used to include quotations within your document. They delimited with double underscores (____)

1____
2She sells seashells by the seashore
3____

Literal Blocks#

These are used to display preformatted text, such as code snippets or data. They are delimited with periods (….)

1....
2This is a literal block
3You can display preformatted text here.
4....

Block metadata#

AsciiDoc lets you assign metadata to any block to add context or modify its presentation. Metadata helps control how a block is rendered and can include elements like titles, identifiers, styles, and named attributes.

Types of MetaData#

Several types of metadata can be added to your content.

• Title

A block title serves as a heading for the content within the block, providing readers with an immediate understanding of its purpose or context. The delimiter for a title is a period (.), followed by the title text on a new line, directly before the block content.

• Id (Anchor)

An id, or anchor, uniquely identifies a block and allows for the creation of internal links within a document for easy navigation. The delimiter for an id is double square brackets ([[id]]), placed immediately before the block content.

• Style

The style attribute specifies the appearance or behavior of a block and is the first unnamed attribute applied to a block. The delimiter used for a style is a pair of square brackets with the style name specified, placed just before the block content.

• Named Block Attributes

Named block attributes provide additional details or modify the behavior of a block. These attributes are included within square brackets ([]), following the style if it is present. Attributes are comma-separated, with the first attribute indicating the style, followed by additional attributes.

Some metadata, such as the title, supplement the content, while others, such as style, dictate the block conversion. You can see an example of block metadata below

1.Lagos, Nigeria
2[[Lagos]]
3[quote, Bola Ahmed Tinubu, from Presidential campaign May 2023]
4____
5We will slow down the economy, by reducing purchasing power. Let's widen...the tax net
6____

On extraction, the metadata will look like this

Title

Lagos, Nigeria

Id

Lagos

Style

quote

Named block attributes

attribution
    Bola Ahmed Tinubu

citetitle from Presidential campaign May 2023

Masquerading blocks#

Masquerading blocks allow a block to take on the appearance of another element by applying specific roles or attributes. This can be useful for customizing the presentation of your content. The example block below has a masquerade attribute, allowing it to act as a masquerade block.

1[.masquerade]
2====
3This block masquerades as a different element using a role attribute.
4====

Admonition Blocks#

Admonition blocks in AsciiDoc are special blocks used to draw attention to important information within a document. These blocks can be used to highlight warnings, notes, tips, and other types of advice or cautionary messages.

Each admonition block is identified by a keyword like “NOTE,” “TIP,” “WARNING,” or “IMPORTANT,” and is visually distinct, making it easier for readers to notice and understand the significance of the content.

The syntax is shown below

 1
 2NOTE: Please note that...
 3
 4TIP: Pro tip...
 5
 6IMPORTANT: Don't forget...
 7
 8WARNING: Watch out for...
 9
10CAUTION: Ensure that...

Listing and Source code blocks#

Source code blocks are specialized blocks designed to display source code with syntax highlighting. These blocks emphasize code structure by colorizing keywords, types, and other elements.

1[source,python]
2----
3require 'sinatra'
4
5
6get '/hi' do
7  "Hello World!"
8end
9----

Open Blocks#

Open blocks allows you to group various elements together such as paragraphs, lists, or even other blocks, treating them as a single unit without imposing any specific formatting or semantics.

1[sidebar]
2.Related information
3--
4This is aside text.
5
6It is used to present information related to the main content.
7--

Passthrough blocks#

This block allows the content to be passed directly through to the output document without any processing by the AsciiDoc parser. A passthrough block can be extremely useful when you encounter a complex requirement that can’t be met using standard AsciiDoc syntax.

 1++++
 2<!DOCTYPE html>
 3<html>
 4  <head>
 5    <title>Passthrough Example</title>
 6  </head>
 7  <body>
 8    <p>This is a paragraph in HTML included as a passthrough block in AsciiDoc.</p>
 9  </body>
10</html>
11++++

Delimiters optional#

Delimiters define the start and end of a block. For instance, when you create a block, you typically enclose it with specific delimiters like —- for an open block or ++++ for a passthrough block. However, some delimiters can be optional depending on how you’re structuring your document. You can create lists without explicitly defining delimiters like *, -, or +. These can sometimes be omitted if the context makes it clear.

1This is a paragraph.
2
31. First item
42. Second item
53. Third item
6
7Another paragraph.

Table#

A table is essentially a delimited block, with the number of columns determined by the first non-blank line inside the |=== delimiters. If each column title is on a separate line, the cols block attribute is required to explicitly state the number of columns, with the * repeat operator used to apply uniform formatting across columns.

 1[cols=2*]
 2|===
 3|Firefox
 4|Web Browser
 5
 6|Ruby
 7|Programming Language
 8
 9|TorqueBox
10|Application Server
11|===

You can mark the first row as a header by setting the header option, which ensures the titles are clearly distinguished from the data,

 1
 2[cols=2*,options=header]
 3|===
 4|Name
 5|Group
 6
 7|Firefox
 8|Web Browser
 9
10|Ruby
11|Programming Language
12
13...
14|===