generatePDF

Timo Abele Johannes Thorn Ralf D. Müller Jody Winter stehlih Ralf D. Müller Alexander Schwartz Dr. Stefan Pfeiffer Lars Francke

2 minutes to read

About This Task

This task makes use of the asciidoctor-pdf plugin to render your documents as pretty PDF files. Files are written to build/pdf. The PDF is generated directly from your AsciiDoc sources. There is no need for an intermediate format or other tools. The result looks more like a nicely rendered book than a print-to-PDF HTML page.

For a file to be rendered, it has to be configured in the doctoolchainConfig.groovy file. There you will find a section that looks like this:

inputFiles = [
        [file: 'manual.adoc',       formats: ['html','pdf']],
        /** inputFiles **/
]

Add the files that you want to be rendered, along with the desired format. In this case pdf.

Hint

Why do you need to configure the files to be rendered?

Asciidoctor renders all .adoc files by default. It doesn’t matter if they are the main documents or chapters you want to include. Most people only want to convert selected files to PDF, so that’s why you need to configure which ones.

Creating a Custom PDF Theme

If you want to change colors, fonts or page headers and footers, you can do so by creating a custom-theme.yml file. Copy the file src/docs/pdfTheme/custom-theme.yml from docToolchain to your project and reference it from your main .adoc`file by setting the `:pdf-themesdir:. In addition, set the :pdf-theme: to the name of your theme. In this case custom. For example, insert the following at the top of your document to reference custom-theme.yml from the /pdfTheme folder.

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

Further Reading and Resources

Source

Show source code of scripts/AsciiDocBasics.gradle or go directly to GitHub · docToolchain/scripts/AsciiDocBasics.gradle.
scripts/AsciiDocBasics.gradle
task generatePDF (
        type: AsciidoctorTask,
        group: 'docToolchain',
        description: 'use pdf as asciidoc backend') {

    attributes (
        'plantUMLDir'         : file("${docDir}/${config.outputPath}/pdf/images/plantUML/").path,
    )

    outputDir = file(targetDir + '/pdf/')

    attributes (
        'data-uri': 'true',
        'plantUMLDir'         : file("${docDir}/${config.outputPath}/images/").path,
        'imagesoutdir'        : file("${docDir}/${config.outputPath}/images/").path
    )

    def sourceFilesPDF = findSourceFilesByType(['pdf'])
//    onlyIf {
//        sourceFilesPDF
//    }

    sources {
        sourceFilesPDF.each {
            include it.file
            logger.info it.file

            File useFile = new File(srcDir, it.file)
            if (!useFile.exists()) {
                throw new Exception ("""
                The file $useFile in PDF config does not exist!
                Please check the configuration 'inputFiles' in $mainConfigFile.""")
            }
        }
    }

    outputOptions {
        backends = ['pdf']
    }

    doFirst {
        if (sourceFilesPDF.size()==0) {
            throw new Exception ("""
            >> No source files defined for type 'pdf'.
            >> Please specify at least one inputFile in your docToolchainConfig.groovy
            """)
        }
    }

    /**
    //check if a remote pdfTheme is defined
    def pdfTheme = System.getenv('DTC_PDFTHEME')
    def themeFolder = pdfTheme.md5()
    if (pdfTheme) {
        //check if it is already installed
        //TODO: finish this...
    }
    **/
}