Skip to content

AsciiDoctor tips

Jump to bottom
Thomas SCHWENDER edited this page Nov 16, 2016 · 38 revisions

AsciiDoc(tor) Tips

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 <Sublime Text 3 install dir>/Data/Packages/AsciiDoc folder

Warning

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

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

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.

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

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.

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

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