AsciiDoctor tips

AsciiDoc(tor) Tips

Table of Contents

• Line breaks in AsciiDoc lists
• Display table of content in GitHub pages, Chrome, etc.
• Emoji (emoticon, smiley) support in AsciiDoctor Chrome Extension
• "incompatible character encodings: UTF-8 and CP850" error
• DZSlides backend (slides generation)

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

• https://github.com/jbake-org/jbake/issues/80#issuecomment-35131093

• https://github.com/jbake-org/jbake/issues/144#issuecomment-57390764

• You should also check the table of content section in the official AsciiDoctor user manual.

• For Chrome (through Asciidoctor.js Live Preview), see https://github.com/asciidoctor/asciidoctor-chrome-extension#troubleshooting

You can also have a look at http://asciidoctor.org/news/2014/02/04/github-asciidoctor-0.1.4-upgrade-5-things-to-know/#5-table-of-contents

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

• https://github.com/asciidoctor/asciidoctor/pull/310

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

Here is also a Stackoverflow article on how to change an encoding in Ruby: http://stackoverflow.com/questions/15120955/ruby-how-to-specify-character-encoding-of-the-file-in-the-command-line-eexi

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.