Skip to content

AsciiDoctor tips

Jump to bottom
Thomas SCHWENDER edited this page May 28, 2021 · 38 revisions

AsciiDoc(tor) Tips

💡

Have a look at the source of the AsciiDoctor manual when you need some examples on a precise AsciiDoctor syntax.

AsciiDoc support in Sublime Text 3

  1. First, you have to download to download the zip containing all the source files from the GitHub repo of the AsciiDoc plugin for Sublime Text.

  2. Then, you have to extract all its content in the %APPDATA%/Roaming/Sublime Text 3/Packages/AsciiDoc folder
    (The package folder can be retrieve through the menu Preferences > Browse Packages…)

⚠️

Syntax highlighting works best with Sunburst or Twilight theme. For other themes, you may have to customize them.

Back quote and single quote side by side

Having those 2 characters side by side can result in some unwanted substitution.
To avoid those, you can insert an {empty} intrinsic attribute between them.

Example:

  • without {empty}

    `wljmxclient.jar`'s MANIFEST ClassPath

    renders as:

    `wljmxclient.jar’s MANIFEST ClassPath

    which is not what was expected, to know having wljmxclient.jar formatted as source code.

  • with {empty}

    `wljmxclient.jar`{empty}'s MANIFEST ClassPath]

    renders as:

    wljmxclient.jar's MANIFEST ClassPath

    In this last case, wljmxclient.jar is formatted as source code.

Display table of content in GitHub pages, Chrome, etc.

To display a table of content in GitHub pages (or in AsciiDoctor Chrome Extension, or, more generally everywhere…​), 3 solutions are possible:

  • Using :toc-placement: preamble

    = My Document
:toc:
:toc-placement: preamble

When using this method, you MUST add a preamble (the current line) to have the table of content displayed

== First section
Some text.

== Second section
Some other text.

  • Using :toc-placement!:

    = My Document
:toc:
:toc-placement!:

toc::[]

== First section
Some text.

== Second section
Some other text.

  • Using :toc: macro

    = My Document
// we use this method for the current GitHub wiki page
:toc: macro

toc::[]

== First section
Some text.

== Second section
Some other text.

Check following links for more info on this bug (after all, it should work with only setting the :toc: attribute 😉):

Disable caption and numbering for all kinds of elements

  • To turn off caption and numbering for some specific element, you need to set a :XXX-caption!: attribute in the document header:

    // To turn off figure caption labels and numbers
:figure-caption!:
// Same for examples
:example-caption!:

  • BUT, to disable caption and numbering for ALL elements in the whole document, you need to use the caption attribute, but without exclamation mark:

    // do NOT use an exclamation mark if you want to turn off all captions and numbering
:caption:

DZSlides backend (slides generation)

  • You need to give a name to images to have them autoresize:

image::images/an_image.jpg[title="a_title"]

  • Apparently, you need the thread_safe gem when generating the slides to have them work correctly.

Emoji (emoticon, smiley) support in AsciiDoctor Chrome Extension

This support was added in version 1.5.2.120.
You can see it there: https://github.com/asciidoctor/asciidoctor-chrome-extension

Here are some examples:

emoji:heart[2x] // the "[2x]" is a size modifier
emoji:rage[]
💡
 As explained in the user manual, you can change the icon size with the syntax icon:heart[2x].

For a complete list of all emoji supported and their options, have a look at: https://github.com/asciidoctor/asciidoctor-chrome-extension/blob/master/app/js/vendor/asciidoctor-emoji-inline-macro.js
You will somehow find a reference to http://www.webpagefx.com/tools/emoji-cheat-sheet/ which gives you the whole list.

Emoji as Unicode characters

Since the release of October 2010, the Unicode Standard was updated to support emoji.
It means that using their Unicode character, emojis can now be added nearly anywhere: in your mail subject, in GitHub, Sublime Text and almost all text editors.

As a consequence, it is not needed anymore to use either icon:heart[2x] or :wink: notation.

You can find all the emojis Unicode character in Emojipedia

You can even notice that, when starting to type :xxx in GitHub editor, it now automatically propose the substitution with the corresponding Unicode character 😉

"incompatible character encodings: UTF-8 and CP850" error

This is an AsciiDoctor error which is described here:

As explained, this is an encoding issue for which the workaround is to force the encoding of Ruby in the AsciiDoctor script.
Just replace

#!<ruby_install_path>/bin/ruby.exe

with

#!<ruby_install_path>/bin/ruby.exe -Eutf-8

in scripts:

  • <ruby_install_path>/bin/asciidoctor

  • <ruby_install_path>/bin/asciidoctor-safe

Line breaks in AsciiDoc lists

For line break in AsciiDoc lists, set the following attribute in the document’s header:

:lb: pass:[<br> +]

You can then use {lb} in a list to leave a blank line in a list.

Line breaks in stem scientific formulas

For line break in stem scientific formulas, use "\\" at the end of a line:

[stem]
++++
f(x) = 42 * x \\
g(x,y) = x / y
++++

Open blocks to avoid having a style used for the preamble line

To avoid having the preamble bigger than the following text, you can use open blocks:

= My document title

--
This preamble will *not* be bigger than the following text.
--

== A first section
Here is some text!

Open blocks to handle list item continuation

This use is described here.
By using open blocks, you can, after having add a nested list, continue typing at the same level as its parent.
Example:

* List item one. +
Some text.
* List item two continued with an open block. +
Some text *before* the block
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item continuation. +
This paragraph is part of the preceding list item.
b. List item b.

This paragraph belongs to item two of the outer list.
--
+
Some text *after* the block

renders as:

  • List item one.
    Some text.

  • List item two continued with an open block.
    Some text before the block

    This paragraph is part of the preceding list item.

    1. This list is nested and does not require explicit item continuation.
      This paragraph is part of the preceding list item.

    2. List item b.

    This paragraph belongs to item two of the outer list.

    Some text after the block

Render URL in block quote declaration

To allow the rendering of an URL in a quote block declaration, you need to surround the URL with single quotes, as shown below:

[quote,Michael Feathers,'author of http://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052[Working Effectively with Legacy Code]']
____
Clean code was written by someone who cares.
____

Spaces in image filename

Having spaces in an image filename is not recommended.
That’s the same thing for each <target> part of a macro (image being one):

  • <name>:<target>[<attrlist>] for inline macros

  • <name>::<target>[<attrlist>] for block macros

But, if you really need to have one, you can still replace them by a %20.
Example: image::DevOps%20AceTP.png[title="DevOps Workflow"]

This tip can be found in the AsciiDoc User Guide, §21.1. Inline Macros

Text formatting: adding color

As explained in the Asciidoc documentation (and not the Asciidoctor one), quoted text (bold, italic, etc.) can be given attributes which can be a color.

Example:

That's [green]#green#! +
[green]##c##[blue]##o##[red]##l##[yellow]##o##[orange]##r##

will give:
That’s green!
color

This is also indirectly explained in the section 22.5. Custom Styling With Attributes of the Asciidoctor documentation.

⚠️
 Unfortunately, this is not yet supported by GitHub Asciidoctor preview, see https://github.com/asciidoctor/asciidoctor-pdf/issues/376.

Another way to do it is to use the Triple-plus passthrough block and custom HTML, like this:

+++<span style="font-weight: bold; color: #FF0000">Architecture</span>+++

Which gives:
Architecture

Unfortunately, this one too is not yet supported by GitHub Asciidoctor preview.

Video rendering on GitHub or browser

We can use AsciiDoctor Conditional Directives to correctly render videos, depending on if document is on GitHub or on browser (using AsciiDoctor.js Live Preview on Chrome by example).
As a reminder, GitHub doesn’t support (2016/06/12) the video macro.

ifdef::env-github[]
https://www.youtube.com/watch?v=4To7s3qln2s[vidéo sur YouTube]
endif::[]

ifdef::env-browser[]
video::4To7s3qln2s[youtube, width=640, height=480]
endif::[]

Of course, you can either use ifdef or ifndef depending of the situation.

Clone this wiki locally