asciidoctor-html-template

1. doc-as-code

1.1. Overview

The purpose of this template is to convert adoc-Files to html-Files These files are divided in html-documents and html-slides. The slides are rendered using revealjs.

The convertion of the adoc-files is processed in a docker-container.

1.2. Usage

1.2.1. Initial Configuration

• After templating this repo commit and push the demo page

• Set Settings - Pages - Branch: gh-pages - Folder: / (root)

  Details

  

1.2.2. Accessing the Website(s) for docs

• https://<github-repo-owner>.github.io/<github-repo-name>

  • ie https://htl-leonding-college.github.io/asciidoctor-html-template

1.2.3. Accessing the Website(s) for slides

• https://<github-repo-owner>.github.io/<github-repo-name>/demo/<file-name>

  • ie https://htl-leonding-college.github.io/asciidoctor-html-template/slides/demo.html

1.2.4. Remote Rendering by github-actions

When commiting and pushing the adoc-files into github, they are automatically rendered by github-actions to html in a (new) branch gh-pages. All sub-folders with adoc-files are included.

1.2.5. Local Rendering

Because the rendering with gh-actions on a gh-runner takes time, it is possible to create a local dist-folder with

./local-convert.sh

❗	You need docker installed locally.

You even can publish your locally created html-slides with

./publish.sh

1.3. Customizing

❗	You should not change the scripts in the asciidocs-folder, unless you really know what to do.

• The script are available in the asciidocs-Folder. So you could change the options for the asciidoctor-engine or the version of revealjs.

1.4. Docs

• Asciidoctor Quick Reference

• AsciiDoc Writer’s Guide

• Slides with Asciidoctor for revealjs