Skip to content

AsciiDoctor tips

Jump to bottom
Thomas SCHWENDER edited this page Dec 6, 2015 · 38 revisions

AsciiDoc(tor) Tips

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

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 https://github.com/asciidoctor/asciidoctor/issues/308

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