migrate documentation for the AsciiDoc language

docs/asciidoc/modules/blocks/examples/admonition.adoc

+////
+Included in:
+- user-manual: Admonition
+- quick-ref
+////
+
+// tag::para-c[]
+WARNING: Wolpertingers are known to nest in server racks. // <1> <2>
+Enter at your own risk.
+// end::para-c[]
+
+// tag::para[]
+WARNING: Wolpertingers are known to nest in server racks.
+Enter at your own risk.
+// end::para[]
+
+// tag::bl[]
+[IMPORTANT]
+.Feeding the Werewolves
+====
+While werewolves are hardy community members, keep in mind the following dietary concerns:
+
+. They are allergic to cinnamon.
+. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
+. Celery makes them sad.
+====
+// end::bl[]
+
+// tag::bl-c[]
+[IMPORTANT] // <1>
+.Feeding the Werewolves
+==== // <2>
+While werewolves are hardy community members, keep in mind the following dietary concerns:
+
+. They are allergic to cinnamon.
+. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
+. Celery makes them sad.
+====
+// end::bl-c[]
+
+// tag::bl-nest[]
+[IMPORTANT]
+.Feeding the Werewolves
+======
+While werewolves are hardy community members, keep in mind the following dietary concerns:
+
+. They are allergic to cinnamon.
+. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
+. Celery makes them sad.
+======
+// end::bl-nest[]
+
+// tag::b-para[]
+NOTE: An admonition paragraph draws the reader's attention to
+auxiliary information.
+Its purpose is determined by the label
+at the beginning of the paragraph.
+
+Here are the other built-in admonition types:
+
+TIP: Pro tip...
+
+IMPORTANT: Don't forget...
+
+WARNING: Watch out for...
+
+CAUTION: Ensure that...
+// end::b-para[]
+
+// tag::b-bl[]
+[NOTE]
+====
+An admonition block may contain complex content.
+
+.A list
+- one
+- two
+- three
+
+Another paragraph.
+====
+// end::b-bl[]

docs/asciidoc/modules/blocks/examples/block.adoc

+////
+Generic Block example snippets
+
+User Manual: Blocks
+////
+
+// tag::list-title[]
+.TODO list
+- Learn the AsciiDoc syntax
+- Install Asciidoctor
+- Write my document
+// end::list-title[]
+
+// tag::meta-co[]
+.Gettysburg Address // <1>
+[#gettysburg] // <2>
+[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg] // <3> <4> <5>
+____
+Four score and seven years ago our fathers brought forth
+on this continent a new nation...
+
+Now we are engaged in a great civil war, testing whether
+that nation, or any nation so conceived and so dedicated,
+can long endure. ...
+____
+// end::meta-co[]
+
+// tag::opt-listing[]
+[listing]
+sudo dnf install asciidoc
+// end::opt-listing[]
+
+// tag::quote-name[]
+[quote]
+Never do today what you can put off `'til tomorrow.
+// end::quote-name[]

docs/asciidoc/modules/blocks/examples/example.adoc

+////
+Included in:
+
+- user-manual: Example
+- quick-ref
+////
+
+// tag::base[]
+.Sample document
+====
+Here's a sample AsciiDoc document:
+
+[listing]
+....
+= Title of Document
+Doc Writer
+:toc:
+
+This guide provides...
+....
+
+The document header is useful, but not required.
+====
+// end::base[]

docs/asciidoc/modules/blocks/examples/open.adoc

+////
+Included in:
+
+- user-manual: Open Block
+- quick-ref
+////
+
+// tag::base[]
+--
+An open block can be an anonymous container,
+or it can masquerade as any other block.
+--
+// end::base[]
+
+// tag::src[]
+[source]
+--
+puts "I'm a source block!"
+--
+// end::src[]
+
+// tag::sb[]
+[sidebar]
+.Related information
+--
+This is aside text.
+
+It is used to present information related to the main content.
+--
+// end::sb[]

docs/asciidoc/modules/blocks/examples/paragraph.adoc

+// tag::para[]
+Paragraphs don't require any special markup in AsciiDoc.
+A paragraph is just one or more lines of consecutive text.
+
+To begin a new paragraph, separate it by at least one blank line from the previous paragraph or block.
+// end::para[]
+
+// tag::hb-all[]
+Rubies are red, +
+Topazes are blue.
+
+[%hardbreaks]
+Ruby is red.
+Java is beige.
+// end::hb-all[]
+
+// tag::hb[]
+Rubies are red, +
+Topazes are blue.
+// end::hb[]
+
+// tag::hb-p[]
+[%hardbreaks]
+Ruby is red.
+Java is beige.
+// end::hb-p[]
+
+// tag::b-hb[]
+To preserve a line break, end the line in a space followed by a plus sign. +
+This results in a visible line break (e.g., `<br>`) between the lines.
+// end::b-hb[]
+
+// tag::hb-attr[]
+= Line Break Doc Title
+:hardbreaks:
+
+Rubies are red,
+Topazes are blue.
+// end::hb-attr[]
+
+// tag::lead[]
+== Section title
+
+This is a regular paragraph.
+
+[.lead]
+This is a paragraph styled as a lead paragraph.
+// end::lead[]
+
+// tag::no-lead[]
+[.normal]
+This is a normal paragraph, regardless of its position in the document.
+// end::no-lead[]
+
+// tag::b-lead[]
+[.lead]
+This text is styled as a lead paragraph (i.e., larger font).
+// end::b-lead[]

docs/asciidoc/modules/blocks/examples/preamble.adoc

+= The Intrepid Chronicles
+
+This adventure begins on a frigid morning.
+We've run out of coffee beans, but leaving our office means venturing into certain peril.
+Yesterday, a colony of ravenous Wolpertingers descended from the foothills.
+No one can find the defensive operations manual, and our security experts are on an off-the-grid team-building retreat in Katchanga.
+
+What are we going to do?
+
+== Certain Peril
+
+Daylight trickles across the cobblestones...

docs/asciidoc/modules/blocks/examples/quote.adoc

+////
+Included in:
+
+- user-manual: Quotes
+- quick-ref
+////
+
+// tag::bl[]
+[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
+____
+Four score and seven years ago our fathers brought forth
+on this continent a new nation...
+____
+// end::bl[]
+
+// tag::bl-alt[]
+[quote, Thomas Jefferson, Papers of Thomas Jefferson: Volume 11]
+____
+I hold it that a little rebellion now and then is a good thing,
+and as necessary in the political world as storms in the physical.
+____
+// end::bl-alt[]
+
+// tag::para[]
+[quote, Albert Einstein]
+A person who never made a mistake never tried anything new.
+// end::para[]
+
+// tag::para2-c[]
+.After landing the cloaked Klingon bird of prey in Golden Gate park: <.>
+[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home] <.> <.> <.>
+Everybody remember where we parked. <.>
+// end::para2-c[]
+
+// tag::para2[]
+.After landing the cloaked Klingon bird of prey in Golden Gate park:
+[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home]
+Everybody remember where we parked.
+// end::para2[]
+
+// tag::comp[]
+[quote, Monty Python and the Holy Grail]
+____
+Dennis: Come and see the violence inherent in the system. Help! Help! I'm being repressed!
+
+King Arthur: Bloody peasant!
+
+Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That's what I'm on about! Did you see him repressing me? You saw him, Didn't you?
+____
+// end::comp[]
+
+// tag::no-cite[]
+____
+A person who never made a mistake never tried anything new.
+____
+// end::no-cite[]
+
+// tag::abbr[]
+"I hold it that a little rebellion now and then is a good thing,
+and as necessary in the political world as storms in the physical."
+-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
+// end::abbr[]
+
+// tag::md[]
+> I hold it that a little rebellion now and then is a good thing,
+> and as necessary in the political world as storms in the physical.
+> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
+// end::md[]
+
+// tag::md-alt[]
+> > What's new?
+>
+> I've got Markdown in my AsciiDoc!
+>
+> > Like what?
+>
+> * Blockquotes
+> * Headings
+> * Fenced code blocks
+>
+> > Is there more?
+>
+> Yep. AsciiDoc and Markdown share a lot of common syntax already.
+// end::md-alt[]
+
+// tag::link-text[]
+[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
+____
+If you don't know where you are going, any road will get you there.
+____
+// end::link-text[]

docs/asciidoc/modules/blocks/examples/sidebar.adoc

+////
+Included in:
+
+- user-manual: Sidebar
+- quick-ref
+////
+
+// tag::base-c[]
+.AsciiDoc history // <1>
+**** // <2>
+AsciiDoc was first released in Nov 2002 by Stuart Rackham.
+It was designed from the start to be a shorthand syntax
+for producing professional documents like DocBook and LaTeX.
+****
+// end::base-c[]
+
+// tag::base[]
+.AsciiDoc history
+****
+AsciiDoc was first released in Nov 2002 by Stuart Rackham.
+It was designed from the start to be a shorthand syntax
+for producing professional documents like DocBook and LaTeX.
+****
+// end::base[]

docs/asciidoc/modules/blocks/examples/verse.adoc

+////
+Included in:
+
+- user-manual: Quotes
+////
+
+// tag::para[]
+[verse, Carl Sandburg, two lines from the poem Fog]
+The fog comes
+on little cat feet.
+// end::para[]
+
+// tag::bl[]
+[verse, Carl Sandburg, Fog]
+____
+The fog comes
+on little cat feet.
+
+It sits looking
+over harbor and city
+on silent haunches
+and then moves on.
+____
+// end::bl[]

docs/asciidoc/modules/blocks/nav.adoc

+* xref:get-started.adoc[]
+** xref:build-basic-block.adoc[]
+** xref:add-title.adoc[]
+** xref:assign-id.adoc[]
+//** xref:attributes:style.adoc[]
+** Advanced Block Patterns
+*** xref:nest.adoc[]
+*** xref:masquerade.adoc[]
+*** xref:open.adoc[]
+//** Customizing Substitutions
+** xref:troubleshoot-blocks.adoc[]
+* xref:paragraph.adoc[]
+** xref:preamble-and-lead.adoc[]
+** xref:paragraph-alignment.adoc[]
+* xref:line-and-page-breaks.adoc[]
+* xref:horizontal-rule.adoc[]
+* xref:ROOT:comment.adoc[]
+* xref:admonition.adoc[]
+* xref:example.adoc[]
+* xref:sidebar.adoc[]
+* xref:blockquote.adoc[]
+* xref:verse.adoc[]

docs/asciidoc/modules/blocks/pages/abstract.adoc

+= Abstract Block Style
+
+An abstract is a concise overview of a document.
+The `abstract` block style can be placed on an open block or paragraph.
+Here's an example of the abstract block style set on a paragraph:
+
+[source]
+----
+= Document Title
+
+[abstract]
+.Abstract
+Documentation is a distillation of many long adventures.
+
+== First Section
+----
+
+The abstract block style does not require the open block or paragraph to have a title, and it does not depend on a subsequent section to terminate it.
+
+[source]
+----
+= Document Title
+
+[abstract]
+--
+This article will take you on a wonderful adventure of knowledge.
+
+You'll start with the basics.
+Beyond that, where you go is up to you.
+--
+
+Your journey begins here.
+----
+
+TIP: To include a quote at the beginning of a chapter in a book, wrap a quote block inside an abstract block.
+
+There's also an xref:sections:abstract.adoc[abstract section style].

docs/asciidoc/modules/blocks/pages/add-title.adoc

+= Add a Title to a Block
+
+You can assign a title to a block, whether it's styled using its style name or delimiters.
+
+== Block title syntax
+
+A block title is defined on its own line directly above the block's attribute list, opening delimiter, or block content--which ever comes first.
+As shown in <<ex-basic>>, the line must begin with a dot (`.`) and immediately be followed by the text of the title.
+
+.Block title syntax
+[source#ex-basic]
+----
+.This is the title of a sidebar block
+****
+This is the content of the sidebar block.
+****
+----
+
+The next sections will show how to add titles to delimited blocks and blocks with attribute lists.
+
+== Add a title to a delimited block
+
+Any delimited block can have a title.
+If the block doesn't have an attribute list, enter the title on a new line directly above the opening delimiter.
+The delimited literal block in <<ex-title>> is titled _Terminal Output_.
+
+.Add a title to a delimited block
+[source#ex-title]
+----
+.Terminal Output <.>
+.... <.>
+From github.com:asciidoctor/asciidoctor
+ * branch        master   -> FETCH_HEAD
+Already up to date.
+....
+----
+<.> The block title is entered on a new line.
+The title must begin with a dot (`.`).
+Don't put a space between the dot and the first character of the title.
+<.> If you aren't applying attributes to a block, enter the opening delimiter on a new line directly after the title.
+
+The result of <<ex-title>> is displayed below.
+
+.Terminal Output
+....
+From github.com:asciidoctor/asciidoctor
+ * branch        master   -> FETCH_HEAD
+Already up to date.
+....
+
+In the next section, you'll see how a title is placed on a block that has an attribute list.
+
+== Add a title to a block with attributes
+
+When you're applying attributes to a block, the title is placed on the line above the attribute list (or lists).
+<<ex-title-list>> shows a delimited source code block that's titled _Specify GitLab CI stages_.
+
+.Add a title to a delimited source code block
+[source#ex-title-list]
+....
+.Specify GitLab CI stages <.>
+[source,yaml] <.>
+----
+image: node:10.16.3-buster
+stages: [ init, verify, deploy ]
+----
+....
+<.> The block title is entered on a new line.
+<.> The block's attribute list is entered on a new line directly after the title.
+
+The result of <<ex-title-list>> is displayed below.
+
+[caption=]
+.Specify GitLab CI stages
+[source,yaml]
+----
+image: node:10.16.3-buster
+stages: [ init, verify, deploy ]
+----
+
+As shown in <<ex-title-style>>, a block's title is placed above the attribute list when a block isn't delimited.
+
+.Add a title to a non-delimited block
+[source#ex-title-style]
+----
+.Mint
+[sidebar]
+Mint has visions of global conquest.
+If you don't plant it in a container, it will take over your garden.
+----
+
+The result of <<ex-title-style>> is displayed below.
+
+.Mint
+[sidebar]
+Mint has visions of global conquest.
+If you don't plant it in a container, it will take over your garden.
+
+You may notice that unlike the titles in the previous rendered listing and source block examples, the sidebar's title is centered and displayed inside the sidebar's background.
+How the title of a block is displayed depends on the converter and stylesheet you're applying to your AsciiDoc documents.

docs/asciidoc/modules/blocks/pages/admonition.adoc

+= Admonitions
+
+// tag::intro[]
+There are certain statements you may want to draw attention to by taking them out of the content's flow and labeling them with a priority.
+These are called admonitions.
+It's rendered style is determined by the assigned label (i.e., value).
+Asciidoctor provides five admonition style labels:
+
+* `NOTE`
+* `TIP`
+* `IMPORTANT`
+* `CAUTION`
+* `WARNING`
+
+.Caution vs. Warning
+[#caution-vs-warning]
+****
+When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably.
+Here's a simple rule to help you differentiate the two:
+
+* Use *CAUTION* to advise the reader to _act_ carefully (i.e., exercise care).
+* Use *WARNING* to inform the reader of danger, harm, or consequences that exist.
+
+To find a deeper analysis, see https://www.differencebetween.com/difference-between-caution-and-vs-warning/.
+****
+
+When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use.
+The label must be uppercase and followed by a colon (`:`).
+
+.Admonition paragraph syntax
+[source#ex-label]
+----
+include::example$admonition.adoc[tag=para-c]
+----
+. The label must be uppercase and immediately followed by a colon (`:`).
+. Separate the first line of the paragraph from the label by a single space.
+// end::intro[]
+
+The result of <<ex-label>> is displayed below.
+
+:icons!:
+include::example$admonition.adoc[tag=para]
+:icons: font
+
+When you want to apply an admonition to complex content, set the label as a style attribute on a block.
+As seen in the next example, admonition labels are commonly set on example blocks.
+This behavior is referred to as *masquerading*.
+The label must be uppercase when set as an attribute on a block.
+
+.Admonition block syntax
+[source#ex-block]
+----
+include::example$admonition.adoc[tag=bl-c]
+----
+. Set the label in an attribute list on a delimited block.
+The label must be uppercase.
+. Admonition styles are commonly set on example blocks.
+Example blocks are delimited by four equal signs (`====`).
+
+The result of <<ex-block>> is displayed below.
+
+:icons!:
+include::example$admonition.adoc[tag=bl-nest]
+:icons: font
+
+In the examples above, the admonition is rendered in a callout box with the style label in the gutter.
+You can replace the textual labels with icons by setting the `icons` attribute on the document.
+This is how the WARNING admonition paragraph renders when icons is set and assigned the `font` value.
+
+.Admonition paragraph with icons set
+[source#ex-icon]
+----
+:icons: font
+
+include::example$admonition.adoc[tag=para]
+----
+
+The result of <<ex-icon>> is displayed below.
+
+include::example$admonition.adoc[tag=para]
+
+Learn more about using Font Awesome or custom icons with admonitions in xref:macros:icons.adoc[].

docs/asciidoc/modules/blocks/pages/assign-id.adoc

+= Assign an ID
+
+You can assign an ID to any block using an attribute list.
+Once you've assigned an ID to a block, you can use that ID to link to it using a cross reference.
+
+== Block ID syntax
+
+An ID is assigned to a block by prefixing the ID value with a hash (`#`) and placing it in the block's attribute list.
+
+[source]
+----
+[#the-id-of-this-block]
+====
+Content of delimited example block
+====
+----
+
+Let's go through some examples of assigning an ID to a block with several attributes, a title, and delimiters.
+
+== Assign an ID to a block with attributes
+
+In this section, we'll assign an ID to this blockquote:
+
+[quote#roads,Dr. Emmett Brown,Back to the Future]
+Roads? Where we're going, we don't need roads.
+
+When the style attribute is explicitly assigned to a block, the style name is always placed in the first position of the attribute list.
+Then, the ID is attached directly to the end of the style name.
+
+The blockquote with an assigned style and ID in <<ex-style-id>> shows this order of attributes.
+
+
+.Assign a style and ID to a block
+[source#ex-style-id]
+----
+[quote#roads]
+Roads? Where we're going, we don't need roads.
+----
+
+Since <<ex-style-id>> is a blockquote it should have some attribution and citation information.
+In <<ex-cite>>, let's attribute this quote to its speaker and original context using the positional attribution attributes that are built into the `quote` style.
+
+
+.Assign a style, ID, and positional attributes to a block
+[source#ex-cite]
+----
+[quote#roads,Dr. Emmett Brown,Back to the Future]
+Roads? Where we're going, we don't need roads.
+----
+
+Except when the `role` and `options` attributes are assigned values using their shorthand syntax (`.` and `%`, respectively), all other block attributes are typically separated by commas (`,`).
+
+////
+
+In addition to a title, a block can be assigned additional metadata including:
+
+* ID (xref:attributes:id.adoc#anchor[anchor])
+* Block style (first positional attribute)
+* Block attributes
+
+Here's an example of a quote block with metadata:
+
+[source]
+----
+include::example$block.adoc[tag=meta-co]
+----
+<1> Title: Gettysburg Address
+<2> ID: gettysburg
+<3> Block name: quote
+<4> attribution: Abraham Lincoln (Named block attribute)
+<5> citetitle: Address delivered at the dedication of the Cemetery at Gettysburg (Named block attribute)
+
+TIP: A block can have multiple block attribute lines.
+The attributes will be aggregated.
+If there is a name conflict, the last attribute defined wins.
+
+Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is converted, such as the block name.
+////

docs/asciidoc/modules/blocks/pages/blockquote.adoc

+= Blockquotes
+
+Prose excerpts, quotes and verses share the same syntax structure, including:
+
+* block name, either `quote` or `verse`
+* name of who the content is attributed to
+* bibliographical information of the book, speech, play, poem, etc., where the content was drawn from
+* excerpt text
+
+== Basic quote syntax
+
+// tag::basic[]
+For content that doesn't require the preservation of line breaks, set the `quote` attribute in the first position of the attribute list.
+Next, set the attribution and relevant citation information.
+However, these positional attributes are optional.
+
+.Anatomy of a basic quote
+[#ex-basic]
+----
+[quote, attribution, citation title and information]
+Quote or excerpt text
+----
+
+If the quote is a single line or paragraph, you can place the attribute list directly on top of the text.
+
+.Quote paragraph syntax
+[source#ex-style]
+----
+include::example$quote.adoc[tag=para2-c]
+----
+<.> Mark lead-in text explaining the context or setting of the quote using a period (`.`). (optional)
+<.> For content that doesn't require the preservation of line breaks, set `quote` in the first position of the attribute list.
+<.> The second position contains who the excerpt is attributed to. (optional)
+<.> Enter additional citation information in the third position. (optional)
+<.> Enter the excerpt or quote text on the line immediately following the attribute list.
+
+The result of <<ex-style>> is displayed below.
+
+include::example$quote.adoc[tag=para2]
+
+== Quoted block
+
+If the quote or excerpt is more than one paragraph, place the text between delimiter lines consisting of four underscores (`+____+`).
+
+.Quote block syntax
+[source#ex-block]
+----
+include::example$quote.adoc[tag=comp]
+----
+
+The result of <<ex-block>> is displayed below.
+
+include::example$quote.adoc[tag=comp]
+
+Asciidoctor also provides three alternative ways to markup quotes and prose excerpts.
+// end::basic[]
+
+== Quoted paragraph
+
+You can turn a single paragraph into a blockquote by:
+
+. surrounding it with double quotes
+. adding an optional attribution (prefixed with two dashes) below the quoted text
+
+.Quoted paragraph syntax
+[source#ex-quoted]
+----
+include::example$quote.adoc[tag=abbr]
+----
+
+The result of <<ex-quoted>> is displayed below.
+
+include::example$quote.adoc[tag=abbr]
+
+=== Markdown-style blockquotes
+
+Asciidoctor supports Markdown-style blockquotes.
+
+.Markdown-style blockquote syntax
+[source#ex-md,markdown]
+----
+include::example$quote.adoc[tag=md]
+----
+
+The result of <<ex-md>> is displayed below.
+
+include::example$quote.adoc[tag=md]
+
+Like Markdown, Asciidoctor supports block content inside the blockquote, including nested blockquotes.
+
+.Markdown-style blockquote containing block content
+[source#ex-md-block,markdown]
+....
+include::example$quote.adoc[tag=md-alt]
+....
+
+Here's how the conversation from <<ex-md-block>> is rendered.
+
+include::example$quote.adoc[tag=md-alt]

docs/asciidoc/modules/blocks/pages/build-basic-block.adoc

+= Build a Basic Block
+:y: Yes
+:n: No
+
+== Delimited blocks
+
+Block content can be styled by enclosing it in a set of delimiters.
+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 (`+****+`).
+
+. Enter the opening delimiter at the beginning of a new line and then press kbd:[Enter].
++
+[source]
+----
+Text in your document.
+
+****
+
+----
+
+. 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.
++
+[source]
+----
+Text in your document.
+
+****
+This is content in a sidebar block.
+
+image::name.png[]
+
+This is more content in the sidebar block.
+----
+
+. To end the delimited block, press kbd:[Enter] at the end of your last line of content.
+On the new line, type the closing delimiter.
++
+[source]
+----
+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:
+
+[source]
+....
+include::example$block.adoc[tag=opt-listing]
+....
+
+or single-line quotes:
+
+[source]
+----
+include::example$block.adoc[tag=quote-name]
+----
+
+== Built-in block styles summary
+// This section is just hanging here for the moment, it's not its final destination, I just didn't want to comment it out.
+
+The following table identifies the built-in block styles, their delimiter syntax, purposes, and the substitutions performed on their contents.
+
+include::partial$block-name-table.adoc[]
+
+////
+This table shows the substitutions performed by each substitution group referenced in the previous table.
+
+include::partial$subs-group-table.adoc[]
+
+OMG. What does this random tip apply to????
+TIP: Surround an attribute value with single quotes in order to apply normal substitutions.
+////

docs/asciidoc/modules/blocks/pages/example.adoc

+= Example Blocks
+// Moved upstream from the Antora documentation at docs.antora.org
+:example-caption!:
+
+On this page, you'll learn:
+
+* [x] How to mark up an example block with AsciiDoc.
+
+An example block is useful for visually delineating content that illustrates a concept or showing the result of an operation.
+
+An example can contain any type of content and AsciiDoc syntax.
+Normal substitutions are applied to example content.
+
+== Example style syntax
+
+If the example content is contiguous, i.e., not interrupted by blank lines, the block style name `example` can be placed directly on top of the text in an attribute list (`[]`).
+
+.Assign example block style to paragraph
+[source#ex-style]
+----
+.Optional title
+[example]
+This is an example of an example block.
+----
+
+The result of <<ex-style>> is displayed below.
+
+.Optional title
+[example]
+This is an example of an example block.
+
+[#delimited]
+== Delimited example syntax
+
+If the example content includes multiple blocks or content separated by blank lines, place the content between delimiter lines consisting of four equals signs (`pass:[====]`).
+
+You don't need to set the block style name when you use the example delimiters.
+
+.Example block delimiter syntax
+[source#ex-block]
+----
+.Onomatopoeia
+====
+The book hit the floor with a *thud*.
+
+He could hear doves *cooing* in the pine trees`' branches.
+====
+----
+
+The result of <<ex-block>> is displayed below.
+
+.Onomatopoeia
+====
+The book hit the floor with a *thud*.
+
+He could hear doves *cooing* in the pine trees`' branches.
+====
+
+TIP: xref:admonition.adoc[Complex admonitions] use the delimited example syntax.

docs/asciidoc/modules/blocks/pages/get-started.adoc

+= Get Started with Blocks
+//Block Syntax and Features
+// I want this page to be focused on the block styles - yes, I know that there are more blocks, but that get's really in the weeds and I think those aspects can be addressed in other pages/modules
+
+== What is a block?
+
+CAUTION: This is the generic definition and a placeholder.
+
+In an AsciiDoc document, one or more continuous lines of text is defined as a block element.
+Examples of block elements are tables, callout lists, block macros such as `image::[]`, verse block titles, paragraphs, an attribute entry in the header, and the header as a whole.
+Block elements can be nested within block elements.
+
+== What is a built-in block style?
+
+TBA
+
+== What features can I apply to a block?
+
+TBA