This page contains snippets used in AsciiDoc blogging examples, and it uses include directives to embed content from other files. The main blog entry is the place to look for context.

Let’s kick things off with an example of a simple note admonition.

This is a NOTE admonition with a Lucide info circle icon. It should display with a blue color scheme and an information icon.

It can contain multiple paragraphs, like this second one.

Those ==== demarcation characters and the [NOTE] heading are only necessary when there is something special about your admonition content, such as multiple paragraphs or distinct styling.

Normally, this works just fine to create an admonition block.

And blogging in standardized lightweight markup doesn’t get much simpler than that.

def hello_world message="Hello, world!", case="upper" (1)
  message_cased = case == "upper" ? message.upcase : message.downcase (2)
  puts message_cased (3)
end
1 defines the method with default parameters
2 processes the message based on the case parameter
3 outputs the processed message
This is a blockquote with a citation. Not something you use in tech writing very often, but quite common in all kinds of blogging.
— Dr Meta
This is some text that I want to highlight as a pull quote. I’ve styled it to be distinct from a standard blockquote, and I use them to preview interesting content that appears later in a post.
Table 1. This table has an automatically numbered caption
Header 1 Header 2 Header 3

Cell 1

Cell 2

Cell 3

Cell 4

Cell 5

Cell 6

Cell 7

Cell 8

Cell 9
Table 2. DocOps Lab ✦ Table of Delightfully Over-Engineered Examples
Multiverse Documentation Planning Matrix — Because simple tables are for mortals

Persona

Toolkit

Sample Artifact

KPI

End-User

Pain points:

  • “Where is the button?”

  • “What’s a token?”

  • “Why is my coffee YAML-flavored?”

AsciiDoc + Antora

Quickstart Guide

Keep it friendly. If the docs feel like a boss fight, you already lost.

⏱ Time-to-First-Success ↓

Admin User

Paligo + Snagit

Troubleshooting Article

☎ Support Tickets/1k users ↓

——— Sprint 42: Docs Ops Experiments ———

Developer

AsciiDoc + Make + PlantUML

Code-Adjacent HOWTO

def deploy env='prod'
  puts "Shipping to #{env}…"
end

⚙ Build Failures Blamed on Docs ↓

Jekyll + Kramdown

API Changelog

  • Sections grouped by part

  • Rendered to HTML/PDF

  • Includes {%- include -%} sorcery

🔁 PRs Merged w/ Docs ↑

Antora + Lunr

“Docs as Feature” RFC

If it isn’t documented, did it even ship?

— A slightly dramatic PM

🧭 Feature Discoverability ↑

——— Release Train: 2.3 “Quantum Marmot” ———

Composite Artifact: “One Doc to Rule Them All”

  • Installation (for Humans)

  • API (for Machines)

  • Architecture (for Historians)

    This cell spans three columns. The rightmost cell is independent.

📈 Adoption Rate ↑

Internal Auditor

AsciiDoc + CSV + a dash of awk

Compliance Matrix (SOC 2, ISO 27001)

σ = 2.3± [1]

Site Reliability Engineer

Runbook Pack

Incident Bundle

  • Playbooks

  • Postmortem template

  • “Pager-Yoga” breathing guide

🔍 Incident Response Time ↓

In conclusion: Tables are for communicating structure, not suffering. Use colspans/rowspans judiciously, and never apologize for beautiful grids.
AsciiDoc

A lightweight markup language that is particularly well-suited for technical documentation and blogging, offering a rich set of features for structuring content.

Markdown

A widely-used lightweight markup language known for its simplicity and ease of use, but with fewer features compared to AsciiDoc.

lightweight markup

A category of markup languages designed to be easy to read and write in plain text, while still allowing for formatting and structuring of content.

An ordered list broken up by an admonition:

  1. Install the NPM packages.

    npm install

  2. Build the app.

    npm run build
Your app is now built and ready to deploy!

  1. Deploy the app.

     npm run deploy
// end::ordered-list[]
An unordered list with deep nesting square bullets

  • First item

    • Sub-item A

      • Sub-sub-item i

      • Sub-sub-item ii

    • Sub-item B

  • Second item

Hyphen bullets with nested ordered list

  • Another first-level item

    1. Nested with dashes

    2. Back to dashes at first level

  • Final item

This would be mainline text that pertains very directly and prominently to the subject. The reader is reading or scanning along, but at this point the author wants to at least introduce some auxiliary content that is relevant but not strictly necessary to the main point, or not a priority at this stage.

A sidebar about sidebar authoring

Sidebars are for textbooks and magazines, at least in the sense of being placed alongside the main content to provide additional context, definitions, or related information.

In HTML, sidebars tend to be for navigation and others static content like masthead info.

But the concept of a content-adjacent sidebars is useful in all kinds of technical writing, including blogging.

Sidebars are for content that is pinned or otherwise relevant to the main topic, but which might be a distraction if dumped inline. It doesn’t quite belong as a section or even a subsection.

The content is not totally required knowledge, but it relates to the content and is not yet a whole other lesson. You want readers to at least be able to make note of it, even at risk of interrupting their reading flow.

In AsciiDoc, sidebars can contain just about any other block or inline content.

When it comes to layout, sidebars should either be collapsed or they should actually be pinned to a bar that runs alongside the content. And in either case, they should be dismissable and stashable so a reader can skip them now but come back to them later.

Below that sidebar element, the mainline text would resume, and the reader can choose to read the sidebar, stash it for later, or skip it altogether.

You can also just stick all your sidebars at the end of the post like little appendices, optionally linking to them from the point in the text where they are relevant.

Example 1. Example block containing a code block

I typically use example blocks to show results, but you can also use them for code listings as well. Let’s make this one a combo.

name: example
array:
  - item1
  - item2
  - item3
def hello_world():
    print("Hello, world!")
This was written in a code block denoted with `+++```+++` literals.

Here come the backticks: ```

This is a literal block, the syntax for which was a simple 1-space indent
This literal block is fenced by four dots (periods), which allows for

non-contiguous

multiline text.
Properly labeled command literal
Use a heading line if you wish to assign a role or other options.
This line was indented by 4 spaces to indicate a literal.
You can keep adding lines that are indented by 4 spaces.
    Some converters will render this embedded in `<code>` tags anyway.
// end::literal-markdown[]

You're looking at HTML right now, sourced inside an AsciiDoc file.

It can be used for anything, including to embed adorable SVG images you come up with after an all-night coding session, like this:

Cute!

This is the built-in role for strikethrough.

This is an alternate method for slightly with fewer characters.

1. Margin of error calculated by a friendly spreadsheet goblin.