Publishing with project files
DITA-OT project files 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.cssrootargs.ftrargs.hdfargs.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
contextthat may include:- an
idthat allows you to refer to this context from other contexts or projects - an
idrefthat refers to another context - a series of
inputfiles (the DITA maps or topics you want to publish) - a
profilewith a series of DITAVAL files used to filter the content of all publications in the deliverable
- an
-
an
outputlocation (relative to the CLI --output directory) -
a
publicationtype that defines:- an
idthat allows you to refer to this publication from other publications or projects - an
idrefthat refers to another publication - a
transtypethat specifies an output format (such as HTML, or PDF) - a series of
paramelements, with any parameters to set for this transformation type, specified vianameand eitherhref,path, orvalue - a
profilewith 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.Figure 1. Sample project file with publication parameter overrides: dita-ot-dir/docsrc/samples/project-files/param-override.xml <project xmlns="https://www.dita-ot.org/project"> <publication transtype="html5" id="common-html5"> <param name="nav-toc" value="partial"/> </publication> <deliverable> <context> <input href="root.ditamap"/> </context> <output href="./out"/> <publication idref="common-html5"> <param name="nav-toc" value="full"/> <!-- override common HTML publication --> </publication> </deliverable> </project> - an
- Use
hreffor 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
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. - Use
valueto 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: