adoc_starter

Table of Contents

• Admonitions
• Setup script
• Script to convert adoc to various formats
  • Syntax
  • Examples
  • Math equations
• Sample adoc document
• Docker environment
• PlantUML
• AsciiDoc attributes
• AsciiDoc Slides

Admonitions

❗	The scripts should be run in Windows Subsystem for Linux environment. For more information on how to enable wsl please refer this page

ℹ️	Admonition icons are not generated in GitHub, unless explicitly declared: ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

Setup script

setup_adoc.sh - to install all required components will install:

• asciidoctor - used to generate html output

• asciidoctor-diagram - used for diagrams

• asciidoctor-pdf - used to generate pdf output

• pandoc - used to generate docx

Run sudo gem update to make sure all gems are up to date.

Full docgen.sh script

    #!/bin/bash

    TOC_LEVEL=5

    if [ -z "$2" ] || [ $2 = "html" ]; then
        asciidoctor -r asciidoctor-diagram -a data-uri -a toc -a toclevels=$TOC_LEVEL -a source-highlighter=rouge $1
    else
        if [ $2 = "docx" ]; then
            if [ ! -f ./myref.docx ]; then
                echo "myref.docx not found, creating default one"
                echo "edit myref.docx style Compact, add bold"
                echo "To add table bordersedit myref.docx, click table, design menu, expand styles, modify table style, select borders, save..."
                pandoc --print-default-data-file reference.docx > myref.docx
            fi
            asciidoctor -b docbook5 -r asciidoctor-diagram -a data-uri -a toc -a toclevels=$TOC_LEVEL -a source-highlighter=rouge --out-file - $1| \
            pandoc --reference-doc=myref.docx --toc --from docbook --to docx --output "${1/.adoc/}".docx
        elif [ $2 = "pdf" ]; then
            asciidoctor-pdf -r asciidoctor-diagram -a data-uri -a toc -a toclevels=$TOC_LEVEL -a source-highlighter=rouge $1
        fi
    fi

Script to convert adoc to various formats

docgen.sh - this will use above mentioned tools to generate great looking documents in html/pdf/docx format.

Syntax

./docgen.sh <your_file.adoc> <desired_ouput [html/docx/pdf]>

Examples

To create HTML document, run:

./docgen.sh test.adoc html or just ./docgen.sh test.adoc - in case of lack of value for format parameter a HTML will be generated by default

To create Word-compatible document, run:

./docgen.sh test.adoc docx

To create a document in PDF format, run:

./docgen.sh test.adoc pdf

Math equations

Use 'stem' to generate Math equations (refer AsciiMath for syntax)

\$sum_(i=1)^n i^3=((n(n+1))/2)^2\$

Sample adoc document

test.adoc - a sample file to play with.

Docker environment

This folder also contains Dockerfile and docker-compose.yml with a basic setup and all libraries pre-installed. To run, simply execute docker-compose run --rm adoc

PlantUML

PlantUML can be used in AsciiDOC with ease. Here are some examples.

And this is one great PlantUML playground to test!

AsciiDoc attributes

Attribute: value	Description
:author:	Set author, enable use of {firstname}, {middlename}, {lastname}
:data-uri:	Embed the images directly into the document
📧	Set author's email
:experimental: true	Turn the experimental features on
:icons: font	Enable admonition icons
:imagesdir: images	Set path where images are stored
:sectnums:	Add numbers to sections
:source-highlighter: rouge	Use rouge for source highlight
:source-language: bash	Set source language
:stem:	Enable STEM equationsm use AsciiMath to test syntax
:toc:	add Table of Contents
:toc-title:	set custom title for Table of Contents
:toclevels: 3	set number of section levels in Table of Contents

AsciiDoc Slides

VS Code Marketplace