Configuring a publication

Main configuration blocks

Groovy

asciidoc {
  publications {
    main {
        sourceSet {
          sources { (1)
          }
          secondarySources { (2)
          }
          resources { (3)
          }
          attributes { (4)
          }
          languages { (5)
          }
        }
        output 'asciidoctorj', 'html' (6)
        output 'asciidoctorj', 'pdf'
    }

  }
}

1	Customise asciidoc sources to be processed.
2	Customise secondary sources. These are any files that should affect the up to date status of a task, but which are not directly handled by `sources` or `resources`. One such example could be the `yaml` configuration for producing PDFs.
3	Additional resources, such as images.
4	Use `attributes` block to configure Asciidoc attributes.
5	Human-language additional configuration.
6	Configures the outputs for this publication. The format is `toolchainName, outputFormat`. See Configuring Toolchains for more info.

Sources and resources

Groovy

asciidoc {
  publications {
    main {
        sourceSet {
            sources {
              include 'foo.adoc', 'star*.adoc' (1)
            }
            resources { (2)
              from 'images', {
                include '*.png'
              }
            }
            sourceDir = 'src/docs/asciidoc' (3)
        }
    }
  }
}

1	A list of file patterns for files to include. If nothing is set, all asciidoc documents are included. It uses an Ant-style PatternSet.
2	Configures a copy specification for resources. These are files, such as images, that are required as part of publication, but not processed by an Asciidoctor engine.
3	It is possible to override the source directory, although the convention of `src/docs/asciidoc<PUBLICATION>` should suffice for most cases.

External sources

Outputs from other tasks can be used as inputs to publications

Groovy

asciidoc {
  publications {
    main {
        sourceSet {
            externalSource {
                builtBy 'anotherTask' (1)
                from tasks.named('anotherTask').map { outputs.files } (2)
                from project(path: ':another', configuration: 'adocGenerator') (3)
                fromPublication('anotherPublication', 'outputName') (4)
                into 'myExt' (5)
            }
        }
    }
  }
}

1	One or more tasks are needed to produce the sources, then the link can be specified here.
2	Source files can be specified as a file collection.
3	If another project produces a configuraiton of source files, even that can be used here.
4	If another publication in the same project has an output formatter that produces content, then link directly to that without using `builtBy` and `from`. The first parameter is the publication name. The second parameter is the name of the output. In cases where the out has an alias, that alias name must be provided here.
5	If the content from the producer needs to be placed into a subfolder relative to the document root of the source set, the it can be configured here.

Asciidoc attributes

asciidoc {
  publications {
    main {
      sourceSet {
          attributes {
              replaceAll 'source-language': 'java' (1)
              addAll 'source-language': 'java', 'project-version' : '1.2.3' (2)
              add 'source-language', 'java' (3)
              add 'publish-time', asTime(LocalTime.now()) (4)
              add 'publish-date', asDate(LocalDate.now()) (5)
              attributeProvider provider { -> [ 'source-language': 'java']} (6)
          }
      }
    }
  }
}

1	Replace all attributes, except those provided by providers with this new set.
2	Add more attributes as a map.
3	Add a single attribute.
4	Add an attribute and force it to be formatted as a time value. Accepts any `java.time.*` values, or anything string that can be parsed.
5	Add an attribute and force it to be formatted as a date value. Accepts any `java.time.*` values, or anything string that can be parsed.
6	Add a provider of attributes.

Default attributes

These attributes are set for every publication:

gradle-project-name: the name of the project.
gradle-project-group: the group of the project, or an empty string if it has none.
gradle-project-version: the version of the project, which is unspecified if it is not set.
gradle-projectdir: the project directory.
gradle-rootdir: the root project directory.
includedir: the directory the sources are converted from. When the publication has external sources, this is the intermediate working directory the sources are copied to. A document can set its own includedir, which replaces this one.

An attribute with the same name in the attributes block overrides the default.

Unlike the classic plugins, the plugins do not set revnumber to the version of the project. revnumber is the version in the revision line of the document header, so a default would replace the version in that line. To use the version of the project anyway, set it in the attributes block:

asciidoc {
  publications {
    main {
      sourceSet {
        attributes {
          add('revnumber', project.version)
        }
      }
    }
  }
}

A document that only shows the version of the project can use {gradle-project-version} instead.

Treating warnings as errors

Groovy

asciidoc {
  publications {
    main {
      sourceSet {
        fatalWarnings ~/missing attribute/ (1)
        missingIncludesAreFatal() (2)
      }
    }
  }
}

1	Provide one or more patterns for scanning log messages. These can be strings, regexes, or anything else can be lazy-evaluated to either.
2	Adds the correct pattern for detecting missing include files.

Linking back to the source directory

Each document gets a gradle-relative-srcdir attribute with the path from its directory back to the source directory. It is . for a document in the source directory, .. for a document in a subdirectory, ../.. for one two levels down, and so on, always with /. That makes it possible to refer to files in the root of the output from documents in any directory:

:stylesdir: {gradle-relative-srcdir}/css
:highlightjsdir: {gradle-relative-srcdir}/highlight

When the publication has external sources, the path leads back to the intermediate working directory that the sources are copied to.

An attribute with the same name in the attributes block overrides it.

Docinfo

There is some DSL support for configuring docinfo. It is important to note that for any of headIsPrivate, headerIsPrivate and footerIsPrivate, it configures it for ALL the source AsciiDoc file within the source set. It is still possible to override a DSL setting within a single source file.

For people that ustilise a common docinfo directory, setting it via the DSL has the benefit that Gradle’s up-to-date checks can then be used to detect changes.

Groovy

asciidoc {
  publications {
    main {
      sourceSet {
        docInfo {
            headIsPrivate = false (1)
            headerIsPrivate = false (2)
            footerIsPrivate = false (3)
            docInfoDir = 'src/docs/docinfo' (4)
        }
      }
    }
  }
}

1	Set whether `head` is private or not.
2	Set whether `header` is private or not.
3	Set whether `footer` is private or not.
4	Configures a common docinfo source directory.

Currently, setting docInfoDir affects all tasks associated with the specific publication where it was set, even those that are no docinfo-aware. For example, if your publication builds both PDF and HTML files, and you change docinfo-header.html, then the PDF output will also be rebuilt. This might be rectified in a future release.