Publishing with project files
DITA-OT 3.4 introduces new project files to define publication projects with multiple deliverables. Projects specify a context, output folder, and publication for each deliverable. A re-usable context groups source files and filters, and a publication defines an output format with transformation parameters. You can pass a project file to the dita command to publish multiple deliverables at once.
About project files
Project files may be defined in one of three formats: XML, JSON, or YAML. The XML format can be validated with a RELAX NG schema provided in the resources folder of the DITA-OT installation (project.rnc).
Whereas .properties files can only be used to set parameters, project files go further, allowing you to define multiple deliverables with separate input files and output folders and formats for each publication. A project file can also refer to other project files, so you can re-use common configuration structures across projects.
Though the exact syntax differs slightly, the basic structure of project files is similar in all supported formats.
You can link to other project files with
Projects can define multiple
deliverables, which consist of:
contextthat may include:
idused to refer to this context from other projects
- a series of
inputfiles (DITA maps)
profilewith a series of DITAVAL files used to filter the content
outputlocation (relative to the CLI --output directory)
- an output format via
- a series of parameters to set for this transformation type, specified via
- an output format via
hreffor web addresses and other resources that should resolve to an absolute URI.
pathfor parameters that require an absolute value, like args.cssroot. Paths may be defined relative to the project file, but are always expanded to an absolute system path.
valueto define strings and relative values for properties like args.csspath, which is used to describe a relative path in the output folder.
Create a project file to define the deliverables in your publication project.
Pass your project file to the dita command to build output.
If needed, pass additional arguments to the dita command to override specific build
For example, to build output once with
dita --project=pdf.xml --args.draft=yes
If your project contains multiple deliverables, you can pass the --deliverable option
to generate output for a single deliverable ID.
dita --project=all.xml --deliverable=htmlhelp