Packager Configuration

Packager configuration settings.

The config.json file is used to configure certain behaviors of the packager and its output. The file is optional; if not present, various fields' default values will be used. The packager infrastructure uses the following fields:

buildLogEntry

The location in the generated archive of the file containing the output of the packager.ftl script. Set to null to omit the build log. Default: .tdbuild.log.

cacheDays

Because packages may be expensive to build, they are cached such that whenever the same package is requested, the already-built version will be sent. The cache will be cleared when any of the documents in the package are modified, or after this number of days. If not specified or negative, caches never expire. If zero, the cache is not used (not recommended). Default: -1.

contextualizedDocLocation

Similar to docLocation, but used for documents (almost always DITA topics) that have been contextualized by another (almost always a DITA map). Since the same source document may appear with multiple contextualizations, it may need to be represented by distinct output artifacts. Default:

${doc.project.name}/${doc.context.folderPath}/${doc.context.basename}_files/${doc.refId}.${config.outputExtensions[doc.extension?lower_case]!doc.extension}

defaultContentEncoding

The default encoding used for files built using <@package.generate>, <@package.generateDoc>, and <@package.preprocessCSS>, when those elements' @encoding attributes are not specified. By default, the encoding setting is used.

docLocation

The location in the generated archive for the file representing a document, as specified via the doc Freemarker variable. The doc variable is of type PackageDocument. This template is used to generate the default locations of generated files, as well as when resolving links between documents. Default: ${doc.project.name}/${doc.folderPath}/${doc.basename}.${config.outputExtensions[doc.extension?lower_case]!doc.extension}

encoding

The character encoding used for metadata and file paths in the generated zip archive. Default: UTF-8.

filename

The name of the generated package file. This value is evaluated as a Freemarker template; see for the list of valid variables. Default: ${params.packageBasename!portal.displayName}-package.zip

logLevel

The threshold level for writing log messages. Must be one of DEBUG, INFO, WARNING or ERROR. Default: INFO.

mimeType

The MIME type of the packages generated by this packager. Used when delivering the package over HTTP. Default: application/zip.

outputExtensions

Maps the source document file extensions to the extension of the file in the package. This allows certain file types, especially XML documents, to use .html as their file extension in the package instead of .xml. .dita, or .ditamap. The default mappings are:

`xml`	`html`
`dita`	`html`
`ditamap`	`html`
`md`	`html`
`eps`	`png`
`cgm`	`png`
`tif`	`png`
`tiff`	`png`

scriptOutputMaxSize

How many characters of the build log to store with the package information document. Because the build logs can be quite large, only a portion of the log should be stored. (The full build log is in the package archive at the buildLogEntry location.) Default: 50000.

The docLocation, contextualizedDocLocation, and filename entries are Freemarker scripts that are used to dynamically calculate values at runtime. These scripts have access to the following variables:

portal: The portal through which the package is being built.
config: The data structure described in config.json.
params: The parameters passed to the packager.
doc (docLocation only): The PackageDocument whose filename to render.

Here is a sample config.json, which uses default settings for all fields:

{
  "mimeType": "application/zip",
  "encoding": "UTF-8",
  "defaultContentEncoding": "UTF-8",
  "cacheDays": -1,
  "scriptOutputMaxSize": 50000,
  "buildLogEntry": ".tdbuild.log", 
  "logLevel": "INFO",
  "filename": "${params.packageBasename!portal.displayName}.zip",
  "docLocation": "${doc.project.name}/${doc.folderPath}/${doc.basename}.${config.outputExtensions[doc.extension?lower_case]!doc.extension}",
  "outputExtensions": {
    "xml": "html",
    "dita": "html",
    "ditamap": "html",
    "md": "html",
    "eps": "png",
    "cgm": "png",
    "tif": "png",
    "tiff": "png"
  }
}