asciidoctor-docker-template

Overview

This is a template-project for

• generating AsciiDoc-Files to html-files and

• deploying the html-files to gh-pages,

• where the gh-pages are located in an branch of the repo.

AsciiDoctor - the software for converting the .adoc-files to .html-files - is executed in a Docker container. So you have nothing to install on your local machine, except Docker

Two scripts are available:

• build-html-docker.sh → builds the .html-pages in the folder gh-pages

• publish-gh-pages.sh → buils and deploys the gh-pages

gh-pages

This are the gh-pages of the template-project.

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

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

• https://htl-leonding-college.github.io/asciidoctor-docker-template/minutes-of-meeting.html

Steps to your own doc-repo

Create your own github-repo

Leave it empty for now.

Clone the Template Repo

git clone https://github.com/htl-leonding-college/asciidoctor-docker-template.git

Change the Remote Origin

For your own documentation change the remote origin to your own empty git-repo and commit your own docs.

• Rename folder of project (from asciidoctor-docker-template to <your-repo-name>)

• Rename Project

• Project Structure - Project - Rename Project

• change git remote

Your current remote origin

git remote -v

Change the remote origin

git remote set-url origin <new repo link>

ie

git remote set-url origin https://github.com/htl-leonding/asciidoctor-docker-testdrive.git

Your new remote origin

git remote -v

In case you change your remote repository to https URL, you will be prompted for your username and password next time you use git fetch, git pull or git push.

source: How to change remote git repository

Commit some Files into the New Repo

Commit the shell-scripts, .ignore-File, …​ into the repo. It is not possible to create gh-pages, without content in the repo.

Activate the gh-pages for your repo.

https://github.com/<your-git-user>/<your-project>/settings

Create the Docs

Create the adoc-Files in the asciidocs-Folder

Caution

Don’t remove docinfo.html. This file is needed for highlighting.

The Header of the adoc-File

= Title
firstname lastname <email>
1.0, yyyy-mm-dd
:sourcedir: ../src/main/java
:icons: font
:toc: left

For images use the image-folder

Necessary Frameworks

For RevealJS the revealjs-folder will be added automatically

Available scripts

Important

Before using the scripts, revisit them carefully.

script	purpose
build-html-docker.sh	creates the html-output
build-pdf-docker.sh	creates the pdf-output
build-reveal-docker.sh	creates the reveal-output for generating slides
download-reveal.sh	downloads the reveal-library from the github-repo and unzips the files. This script is used by build-reveal-docker.sh.
build-all.sh	create the html-, pdf-, and revealjs-output
clean-all.sh	deletes all output-files, which are not necessary for the gh-pages
publish-gh-pages.sh	creates the html-output and publish it on the gh-pages.

The Generated Output

gh-pages need the doc-folder for publishing.