asciidoc_html_build

This script will typeset the documents of a given source directory into HTML.

The following parameters are optional:

f

delete the output directory before typesetting

n

turn caching off

o

the output directory ($PWD/build if not given)

s

the source directory ($PWD/src if not given)

*.adoc files inside directories named _includes will not be typeset.

This is useful for AsciiDoc includes.

This scripts configures Asciidoctor to not use webfonts, use local FontAwesome assets, embed images, and inline CSS.

If you want to use custom fonts, this script assumes that the woff2 fonts are found in the <source directory>/fonts directory.

Depending on your use case, you might want to use antora_build instead of this script.

Usage

$ tree --noreport -I scripts
.
└── src
    └── index.adoc
$ scripts/asciidoc/asciidoc_html_build.sh
$ tree --noreport -I scripts
.
├── build
│   └── index.html                                                        (1)
└── src
    └── index.adoc

$ tree --noreport -a /tmp/example
/tmp/example
└── src
    ├── _includes
    │   └── footer.adoc
    ├── a
    │   ├── b
    │   │   └── sub.adoc
    │   └── dir.adoc
    ├── css
    │   └── font-awesome.css                                              (2)
    ├── docinfo
    │   └── docinfo.html                                                  (3)
    ├── fonts
    │   └── fontawesome-webfont-4.7.0.woff2                               (2)
    └── index.adoc
$ cat /tmp/example/src/docinfo/docinfo.html                               (3)
<style>
  pre.rouge .hll {                                                        (4)
    background-color: #ffffe0;
    display: block;
  }
  pre.rouge .hll * {                                                      (4)
    background-color: initial;
  }
</style>
$ cat /tmp/example/src/a/b/sub.adoc
= 1. sub
:source-highlighter: rouge                                                (4)
:rouge-style: github
:docinfo: shared                                                          (3)
:docinfodir: ../../docinfo                                                (3)

[NOTE]                                                                    (2)
====
Test
====

[plantuml]                                                                (5)
....
@startuml

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(p, "Support")

System(s, "Test System")

Rel(p, s, "Uses", "https")

@enduml
....

[,shell,highlight=2..3;5]                                                 (4)
....
A
B
C
D
E
F
G
....

includes::../../_includes/footer.adoc[]
$ scripts/asciidoc/asciidoc_html_build.sh -s /tmp/example/src -o /tmp/example/out
$ tree --noreport -a /tmp/example -I src
/tmp/example
└── out                                                                   (6)
    ├── a
    │   ├── b
    │   │   ├── .asciidoctor                                              (8)
    │   │   │   └── diagram
    │   │   │       └── diag-plantuml-md5-757a0ec403d52693302a4f18fd7ec102.png.cache
    │   │   ├── css
    │   │   │   └── font-awesome.css                                      (7)
    │   │   ├── diag-plantuml-md5-757a0ec403d52693302a4f18fd7ec102.png    (8)
    │   │   ├── fonts
    │   │   │   └── fontawesome-webfont-4.7.0.woff2                       (7)
    │   │   └── sub.html
    │   ├── css
    │   │   └── font-awesome.css                                          (7)
    │   ├── dir.html
    │   └── fonts
    │       └── fontawesome-webfont-4.7.0.woff2                           (7)
    ├── css
    │   └── font-awesome.css                                              (7)
    ├── fonts
    │   └── fontawesome-webfont-4.7.0.woff2                               (7)
    └── index.html
$ scripts/asciidoc/asciidoc_html_build.sh -s /tmp/example/src -o /tmp/example/out -f -n
$ tree --noreport -a /tmp/example -I src
/tmp/example
└── out                                                                   (9)
    ├── a
    │   ├── b
    │   │   ├── css
    │   │   │   └── font-awesome.css
    │   │   ├── fonts
    │   │   │   └── fontawesome-webfont-4.7.0.woff2
    │   │   └── sub.html
    │   ├── css
    │   │   └── font-awesome.css
    │   ├── dir.html
    │   └── fonts
    │       └── fontawesome-webfont-4.7.0.woff2
    ├── css
    │   └── font-awesome.css
    ├── fonts
    │   └── fontawesome-webfont-4.7.0.woff2
    └── index.html
1 the typeset HTML
2 admonitions need Font Awesome
3 custom styles
4 use Rogue source highlighter
5 a document with an PlantUML diagram
6 notice there is no footer.html in an _includes directory
7 Asciidoctor currently does not support a nested set of documents well
8 the files of the diagram cache
9 the output directory has been cleaned (-f) and no files for the cache have been created (-n)

Example

main.adoc, docinfo.html

$ cd scripts/asciidoc/example-html
$ ../asciidoc_html_build.sh

⇒ build/main.html

Prerequisites

More Information