generateHTML & generatePDF

generateHTML and generatePDF are basic tasks which 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, HTML output is rendered as a single page with a table of contents (TOC) on the left. If using the withhelp version, help appears behind question mark icons on the right side of the page. When readers hold their mouse over each icon, help appears.

generatePDF
Figure 2. generated output of generatePDF task

Figure 2 shows you the PDF output. There is a TOC available on the first pages, and a TOC also appears on the left, helping readers navigate the document.

Both HTML and PDF outputs can be styled to suit your needs.

Configuration

Files to convert

For both tasks, the most important configuration is 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. For documents structured using includes, to create a full document (and avoid each chapter being converted to an individual PDF) you’ll need a main AsciiDoc file that includes all chapters.

The inputFiles-map lists all of the main files as well as a list of formats applicable to each. For example, this lets you specify which files should be converted to HTML but not to PDF. You will need to configure this list manually.

If docToolchain converts an unexpected list of files, this is the first place to look when troubleshooting problems.

Working with the PDF style

First, execute ./dtcw copyTheme to copy a simple pdfTheme to your own project. 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, specify the location and other PDF-related attributes in the file that you want to convert. The most important ones are:

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

For this tutorial, navigate to src/docs/arc42/arc42.adoc then add the following to the top of the document:

:pdf-themesdir: ../pdfTheme
:pdf-theme: custom

This will specify that AsciiDoc will find 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. For example :pdf-themessdir: {projectRootDir}/src/docs/pdfTheme will search in /home/myname/projects/demo/src/docs/pdfTheme for the theme.

If you want to use the {projectRootDir} in your editor preview, you must define it as a relative path: 
ifndef:projectRootDir[:projectRootDir: ../../..]

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

Working with the HTML style

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

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