generateHTML & generatePDF

The generateHTML and generatePDF tasks are the most basic tasks which just invoke asciidoctor to generate the output you want.

Linux / WSL2 with bash
./dtcw generateHTML
Windows with Powershell
./dtcw.ps1 generateHTML
output of generateHTML
$ ./dtcw generateHTML
dtcw - docToolchain wrapper V0.23
docToolchain V2.0.0

Bash is running on WSL
this might cause problems with plantUML
see https://doctoolchain.github.io/docToolchain/#wsl for more details

Java Version 11
docker available
home folder exists
use local homefolder install /home/rdmueller/.doctoolchain/
Starting a Gradle Daemon, 22 busy Daemons could not be reused, use --status for details

> Configure project :
arc42/arc42.adoc

> Task :generateHTML
Converting /c/Users/ralfd/projects/dtc-tests/wsl/src/docs/arc42/arc42.adoc

BUILD SUCCESSFUL in 26s
1 actionable task: 1 executed

The output is written to build/html5/arc42/arc42.html and build/pdf/arc42/Arc42.pdf.

generateHTML.dio
Figure 1. generated output of generateHTML task

As you can see in Figure 1, the HTML output is rendered as a single page with a table of contents (TOC) on the left. If you have chosen the withhelp version, you will notice some little question marks on the right. Hover over these with your mouse and you will see the full help text for each paragraph. This way, you can leave these help texts in your docs without annoying your readers.

generatePDF
Figure 2. generated output of generatePDF task

Figure 2 shows you the generated PDF. It also contains a TOC on the first pages and your PDF reader will also show the TOC on the left for you to navigate through the document.

Both, the HTML and PDF output can be styled to fit your needs.

Configuration

Files to convert

For both tasks, the most important configuration is the inputFiles-list at the start of your docToolchainConfig.groovy

inputFiles = [
        //[file: 'doctoolchain_demo.adoc',       formats: ['html','pdf']],
        //[file: 'arc42-template.adoc',    formats: ['html','pdf']],
        /** inputFiles **/
]

Normally, Asciidoctor converts all files it can find. But when you structure your documents with includes, you don’t want each and every chapter to be converted in its own pdf. So, you need a main AsciiDoc file which includes all chapters in order to create a full document.

The inputFiles-map provides a list of all these main files and a list of formats for which the file should be used. This way, you can specify that certain files should be converted to HTML but not to PDF for example.

You need to configure this list manually. So if docToolchain converts an unexpected list of files, this is the first location where you should look for a problem.

PDF Style

To get started, you should execute ./dtcw copyTheme in order to copy a simple pdfTheme to your own project. You will find it in /src/docs/pdfTheme.

Currently, docToolchain uses the asciidoctor-pdf library. The documentation contains a good theming guide.

To activate the new style, you have to tell asciidoctor where to find it. For maximum flexibility, you specify the location and other pdf related attributes in the file you want to convert.

The most important ones are

:pdf-stylesdir: ../pdfTheme
:pdf-style: custom
// only needed when you specify your own fonts
:pdf-fontsdir: ../pdfTheme/fonts

For this tutorial, navigate to `src/docs/arc42/arc42.adoc and add

:pdf-stylesdir: ../pdfTheme
:pdf-style: custom

to the top of the document. This will specify that asciidoc will find the the pdfTheme relative to the document location in ../pdfTheme which will result in src/docs/arc42/../pdfTheme which is equal to src/docs/pdfTheme.

You can also make use of the attribute {projectRootDir} which will contain the absolute path to your project directory. So, :pdf-stylesdir: {projectRootDir}/src/docs/pdfTheme will search in my case in /home/rdmueller/projects/demo/src/docs/pdfTheme for the theme.

in order to use the {projectRootDir} also in your editor preview, define is as relative path, only if it is not already defined:
ifndef:projectRootDir[:projectRootDir: ../../..]

This example, added to the top of your arc42.adoc tutorial file, will set the projectRootDir to the correct folder.

HTML Style

The easiest way to modify the HTML style is to add a pass-through block with the needed CSS styles.

++++
<style>
  h2 {
    color: green;
  }
</style>
++++
for the generateSite task, there is a different mechanism to change the styles if the generated microsite.