Skip to content

AsciiDoctor tips

Jump to bottom
Thomas SCHWENDER edited this page Apr 5, 2016 · 38 revisions

AsciiDoc(tor) Tips

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. == 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.

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 😉):

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
Tip
 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 find a reference to http://www.tortue.me/ which gives you the whole list.

"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

Clone this wiki locally