AsciiDoc Tips and Fragments
Updated 2022-January-31

Page contents

News
Why I created this article
Attributes
- Some built-in attributes
- Some of my custom attributes
Assign multiple IDs to a section
- Reference
Section listed in TOC but not displayed on page
Includes
- Indenting
- Level offsetting
See also
Endnotes

News

2022-January-30 Soft launched⁠^[1] this evolving⁠^[2] article.

ℹ	This is a work in progress.

Because I have a bad memory, I often need to search the web or the AsciiDoc docs for the tips and fragments in this article. Now I can visit this page, which is easy to get to when I’m developing the Infinite Ink website because, thanks to my multi-⁠monitor setup and the hugo server command, this article is easily viewable on my http://localhost:1313/ monitor (at http://localhost:1313/asciidoc-⁠tips-⁠fragments/).

Attributes

To learn about AsciiDoc attributes in general, see:

docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes/

To learn about custom AsciiDoc attributes, see

docs.asciidoctor.org/asciidoc/latest/attributes/custom-attributes/

Some built-in attributes

The following table is forked from docs.asciidoctor.org/asciidoc/latest/attributes/character-replacement-ref/.

Built-in document attributes for character replacement
Attribute name	Replacement text	Appearance
`blank`	nothing
`empty`	nothing
`sp`	space
`nbsp`
`zwsp`
`wj`	⁠	⁠
`apos`	'	'
`quot`	"	"
`lsquo`	‘	‘
`rsquo`	’	’
`ldquo`	“	“
`rdquo`	”	”
`deg`	°	°
`plus`	+	+
`brvbar`	¦	¦
`vbar`	\|	\|
`amp`	&	&
`lt`	<	<
`gt`	>	>
`startsb`	[	[
`endsb`	]	]
`caret`	^	^
`asterisk`	*	*
`tilde`	~	~
`backslash`	\	\
`backtick`	`	`
`two-colons`	::	::
`two-semicolons`	;;	;;
`cpp`	C++	C++
`pp`	++	++

Some of my custom attributes

In addition to the above built-in attributes, I define the following custom attributes.

Specified in "AsciiDoc header" of .adoc file

:octothorpe: &#35;
:colon: &#58;
:rsolidus: &#92;
:underscore: &#95;
:3dashes: pass:q[<nobr>`---`</nobr>]
:4dashes: pass:q[<nobr>`----`</nobr>]

When coding in AsciiDoc, you reference attributes using syntax like this:

Fragment of .adoc file

// A line starting with slash slash (//) is a comment

// Some built-in attributes
{asterisk}
{tilde}

// Some Infinite Ink custom attributes
{octothorpe}
{colon}
{rsolidus}
{underscore}
{3dashes}
{4dashes}

Asciidoctor can transform the above AsciiDoc source fragment to HTML that is rendered like the following in your web browser:

Result

* ~

# : \ _ --- ----

Assign multiple IDs to a section

The source code of Infinite Ink’s qutebrowser Tips and Fragments includes this section heading:

[[_wsl]]
== Calling a bash script from a Windows userscript[[_gitbash]]

Note:

_wsl is the primary ID
_gitbash is the secondary ID

With the above section heading code, each of the following is true.

Both of the next two AsciiDoc source code fragments link to this section heading:

link:/qutebrowser-tips-fragments/#_wsl[userscript on Windows]
link:/qutebrowser-tips-fragments/#_gitbash[userscript on Windows]

In the Asciidoctor-generated table of contents, the next (primary) link is used:

link:/qutebrowser-tips-fragments/#_wsl[Calling a bash script from a Windows userscript]

If you’re interested in this topic, here’s a live link: Calling a bash script from a Windows userscript.

💡	To view or post comments, enable JavaScript.

AsciiDoc Tips and Fragments Updated 2022-January-31

AsciiDoc Tips and Fragments
Updated 2022-January-31