AsciiDoc Guide

About AsciiDoc

Syntax

Document Options

:favicon: ./images/favicon/favicon.png
Experimental Features such as UI Macros
:experimental:
Numbered Headers
:sectnums:
:sectnumlevels: 5
Font Icons by Font Awesome
:icons: font

Headers

Use one or multiple = to indicate header level. The number of = characters indicate the header level , for example: == indicates h2 while === indicates h3, and so on ..

Paragraphs

Code Output 
.Paragraph Optional Title
Some text here.
Paragraph-1 Optional Title

Some text here.

 
.Paragraph Optional Title
 Add one space before line to create literal paragraph.
Paragraph-2 Optional Title
Add one space before line to create literal paragraph.

Blocks

https://asciidoctor.org/docs/user-manual/#url

Code

Output

 
[[anchor-1]]
Some text in paragraph 1
<<anchor-1,Optinal Anchor-1 Title>>

Some text in paragraph 1

Optinal Anchor-1 Title

 
anchor:anchor-2[]
Some text in paragraph 2
xref:anchor-2[Optinal Anchor-2 Title]

Some text in paragraph 2

Optinal Anchor-2 Title

Lists

Unordered Lists

https://asciidoctor.org/docs/user-manual/#unordered-lists

  • Use one or more * characters to indicate list item level.

  • You can use - for top level list items only.

Ordered Lists

Labeled Lists

Labeled lists are useful when you need to include a description or supporting text for each item in a list. https://asciidoctor.org/docs/user-manual/#labeled-list

Code Output 
Title::
    - List Item 1
        ** Child Item 1.1
    - List Item 2
Title

  • List Item 1

    • Child Item 1.1

  • List Item 2

 
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD

Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
Operating Systems
Linux

  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD

  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS

  1. OpenShift

  2. CloudBees

IaaS

  1. Amazon EC2

  2. Rackspace

Tables

Basic Table Structure:

  • Table starts & ends with |===

  • The first line is considered table header, leave empty if there are no table headers.

  • Each cell starts with a pipe ` | `.

  • Columns can be places on one or multiple consecutive lines with no spaces in between.

  • Rows can must have one or more white space between them.

[cols=""] attribute:

  • More columns formating info can be found at https://asciidoctor.org/docs/user-manual/#cols-format

  • Number of values assigned to [cols="1,2,3"] indicates the number of columns.

  • The values can be alignment instructions or styling information (ToDo: can they be both?). Available styles are : d for default paragraph formatting, a for AsciiDOc, e for Italicized text, h for header style, l for literal block formatting, m for monospaced content, s for bold text and v for verse styling.

Col / Row Span

To span 2 columns and 1 row
2.1| ColContent

UI Macros (Experimental)

https://asciidoctor.org/docs/user-manual/#user-interface-macros

kbd:[F11]
menu:View[Zoom > Reset]
btn:[OK]
icon:tags[role="blue",size=2x]
icon:heart[role="red",size=fw,rotate=90, flip=vertical]

Includes

Code

Output

 
This is example how files
can be included.
It's commented because
there no such files. :)

 include::footer.txt[]
 [source,perl]
 include::script.pl[]

This is example how files can be included. It’s commented because there no such files. :)

Converter

Converter Options

All options can be found on the manpage by running asciidoc --help manpage

-f, --conf-file=CONF_FILE
          Use configuration file CONF_FILE.Configuration files processed
          in command-line order (after implicit configuration files). This
          option may be specified more than once.
-s, --no-header-footer
         Suppress document header and footer output.
-o, --out-file=OUT_FILE
         Write output to file OUT_FILE. Defaults to the base name of
         input file with backend extension. If the input is stdin then
         the outfile defaults to stdout. If OUT_FILE is - then the
         standard output is used.
-n, --section-numbers
         Auto-number HTML article section titles. Synonym for --attribute
         numbered.
--theme=THEME
         Specify a theme name. Synonym for --attribute theme=THEME. The
         --theme option is also used to manage theme plugins (see
         [3]PLUGIN COMMANDS).

Custom CSS

Custom UI Macros Menus Styles

menu:Left Bar Menu[Tags > New > some]

<style> .custom-ui-macro-menu-css-v1 .menuseq .menu, . custom-ui-macro-menu-css-v1.menuseq .submenu, .custom-ui-macro-menu-css-v1 .menuseq .menuitem{ padding: 5px; border: 1px dotted #ddd; } .custom-ui-macro-menu-css-v1 .menuseq .menu{ background: hsl(20,20%,90%); } .custom-ui-macro-menu-css-v1 .menuseq .submenu{ background: hsl(200,20%,90%); } .custom-ui-macro-menu-css-v1 .menuseq .menuitem{ background: hsl(160,20%,90%); }

</style> <style> body{ background: #f9f9f9; } #content{ max-width: 1200px; } .sect1{ background: #f4f4f4; padding: 20px; } .sect1+.sect1{ border-top: 1px solid #eee; } .sect2{ background: #fff; padding: 20px; } .sect2+.sect2 { border-top: 1px dotted #e5e5e5; } </style>