Publishing with project files
DITA-OT 3.4 introduced project files that allow you to publish multiple deliverables at once. Each
deliverable specifies a re-usable source context
that groups the maps or topics you want to
publish, an output
folder, and a publication
format (such as HTML, or PDF) with
transformation parameters.
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 with
include
statements. Deliverables, contexts, and publications can either be entirely
self-contained, or reference others with idref
attributes, so you can re-use common
configuration structures across (and within) projects.
args.cssroot
args.ftr
args.hdf
args.hdr
Syntax
Though the exact syntax differs slightly, the basic structure of project files is similar in all supported formats.
The following settings can be defined for each deliverable
:
-
a source
context
that may include:- an
id
that allows you to refer to this context from other contexts or projects - an
idref
that refers to another context - a series of
input
files (the DITA maps or topics you want to publish) - a
profile
with a series of DITAVAL files used to filter the content of all publications in the deliverable
- an
-
an
output
location (relative to the CLI --output directory) -
a
publication
type that defines:- an
id
that allows you to refer to this publication from other publications or projects - an
idref
that refers to another publication - a
transtype
that specifies an output format (such as HTML, or PDF) - a series of
param
elements, with any parameters to set for this transformation type, specified vianame
and eitherhref
,path
, orvalue
- a
profile
with any additional DITAVAL files used to filter the content of the publication (in addition to any filters defined in the map context)
Parameters defined in a publication can override those in other publications that are referenced via
idref
. - an
- Use
href
for web addresses and other resources that should resolve to an absolute URI. Relative references are resolved using the project file as a base directory. - Use
path
for 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. - Use
value
to define strings and relative values for properties like args.csspath, which is used to describe a relative path in the output folder. String values are passed as is.
Project filtering
As of DITA-OT 4.0, you can add DITAVAL filters to both contexts and publications. If a set of filter conditions applies to most or all of your deliverables, then it should probably be defined in a publication, rather than in contexts.
For example, consider a case with 100 maps that have multiple @product
variants, but every one
of which is published in two @audience
conditions (internal or external). If
@audience
is varied in publications, the structure is orthogonal and well-organized: