AsciiDoc Syntax and Features

Using AsciiMath

Include stem into document header

:stem:

Then use inline, e.g.:

stem:[sqrt(4) = 2]

or as block

[stem]
++++
sum_(i=1)^n i^3=((n(n+1))/2)^2
++++

Collapsible Blocks/Sections

.Click to show the content
[%collapsible]
====
Long content here...
====

Tools and Ecosystem

Docker / Podman Container

Including stuff like:

  • Asciidoctor

  • Asciidoctor Diagram with ERD and Graphviz integration (supports plantuml and graphiz diagrams)

  • Asciidoctor PDF

  • Asciidoctor EPUB3

  • Asciidoctor FB2

  • Asciidoctor Mathematical

  • Asciidoctor reveal.js

  • AsciiMath

  • Source highlighting using Rouge, CodeRay or Pygments

  • Asciidoctor Confluence

  • Asciidoctor Bibtex

  • Asciidoctor Kroki

  • Asciidoctor Reducer

Resources:

Using the Image

Using with Podman
podman run -it -v /path/to/docs:/documents/ docker.io/asciidoctor/docker-asciidoctor

afterwards simply run stuff like

asciidoctor doc.adoc
asciidoctor-pdf doc.adoc

Generate OpenAPI Documentation in AsciiDoc

Pull Docker Image

docker pull openapitools/openapi-generator-cli

Generate AsciiDoc

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate -i /local/fahrwege-api.yml -g asciidoc -o /local/adoc-fw

Convert Word to AsciiDoc with Pandoc

docker run --rm --volume "`pwd`:/data" --user `id -u`:`id -g` pandoc/core my-in-file.docx -f docx -t asciidoc --wrap=none --markdown-headings=atx --extract-media=extracted-media  -o my-out-file.adoc