AsciiDoc - Advanced topics

2018-02-23 · 468 words · 3 minute read

Language

AsciiDoc · Advanced

Syntax

The whole syntax can be found in the User Manual: http://asciidoctor.org/docs/user-manual

the source of User Manual can be found here

Code HighLight

More details here: http://asciidoctor.org/docs/user-manual/#source-code-blocks

How to hightlight?

Just add the following at the head of your .adoc document under the title

:source-highlighter: <renderer>

The following renderer exists:

pygments
coderay
rouge [pdf only]
prettify [html only]
highlightjs [html only]

I recommend the renderer pygments (both compatible with HTML and PDF):

:source-highlighter: pygments
:pygments-style: manni
:pygments-linenums-mode: inline

Highlighted code can be added either syntax:

[source,<language>]
# The code without any blank line (single pragraph)

[source,python]
----
# Your Python code ...

# ... with empty lines
----

You can add number of lines by adding linenums at the end of [source] markup:

[source,python,linenums]

Line numbers is (so far) only supported by asciidoc-pdf when using rouge. See Issue #224 for details.

You can force the usage of rouge with following option in command line:
-a source-highlighter=rouge

You can also add the name of the file by adding .<filename> before the [source] markup:

.example.py
[source,python]

Also, you can defined a default language by adding this line in the header (example of Python):

:source-language: python

Example

This is an example of how syntax highlight can look like:

example.py

import logging

def printErr(msg, type='error'):
    sys.stderr.write (msg + "\n")
    logging.info (msg)
    status[type] += 1


class DICT_2_OBJ(object):
    '''Class to tranform a dictionary into an object'''
    def __init__(self, fields): self.__dict__=fields

class TestCase():
    """"
    Generic class for Test Case
    """
    def __init__(self, id='TC-UNKNOWN', tp=None):
        self.id = id
        self.reqs = list()
        self.tp = tp

    def __lt__(self, other):
        return self.id < other.id

Using Icons

Icons

Icons are used for admonition labels, callout numbers and inline symbols. Asciidoctor provides three strategies for display icons: as text, as images or as a characters selected from an icon font. The strategy is controlled using the icons attribute. The default behavior is to display the fallback text.

The easiest way is to use font-based icons:

:icons: font

For other possibilities, refer to User Manual

You can use font icons like this:

icon:wechat[]

And this will how it will look like:

The font icons are based on Font Awesome; a list of available icons can be found here:
https://fontawesome.com

Usually, the version supported is not that latest one.
You might use the version 4.7.0 as a reference

You can even animate icons with spin or pulse:

icon:cog[spin]
icon:spinner[pulse]

This will look like this: and

AsciiDoc-PDF

Set up a format

Refer to Theming Guide.

Themes are defined in YAML format and are loaded via the command line

asciidoctor-pdf <options> -a pdf-style=<theme.yml> <input.adoc>

For example, the following can set-up a page in landscape format:

theme_landscape.yml

page:
  layout: landscape

While the yml file above works, it is better (i.e. looks nicer) to use default_theme.yml in GitHub and update the values you want to change.