This repository tracks the documentation source files for the DITA Open Toolkit project.
Note
The maps in this repository contain references to additional topics that are created at build time from the toolkit’s plug-in configuration.
To generate the missing topics and build the HTML and PDF versions of the documentation, run the Gradle build script from the root level of the
docs
repository and pass the path to your DITA-OT installation as a parameter.
You must have a JRE and a local installation of DITA-OT. There is no need to download and install Gradle.
Type a variant of the following command for your operating system, adjust the path to your DITA-OT installation, and press Enter:
On Linux, macOS, or Git Bash, use ./gradlew
:
./gradlew -PditaHome=/path/to/dita-ot
On Windows, use gradlew.bat
:
gradlew.bat -PditaHome=C:\path\to\dita-ot
You can also specify a single output format. To build HTML for example, add html
to the end of the command:
./gradlew -PditaHome=/path/to/dita-ot html
If all goes well, you receive a "BUILD SUCCESSFUL" message, and the generated DITA topics are written to the extension-points
and parameters
directories in the out
folder of the docs
repository.
This folder is created automatically if it doesn’t exist. (Git ignores the contents so you don’t inadvertently commit these transient output files.)
The develop
branch of the documentation repository may depend on features from recent development versions of DITA Open Toolkit.
To use these features when building the documentation, you may either download the latest development version of the distribution package, or clone the DITA-OT repository and install the bundled plug-ins via dita install
.
We welcome contributions to the DITA-OT documentation. Please review the guidelines for contributing to this repository before creating issues or opening pull requests.
For best results, follow the coding guidelines and best practices outlined in the docs project wiki:
The documentation repository uses the following JavaScript tools to keep source files consistently formatted:
PATH
environment variable.To set these tools up:
npm install
With these tools in place, any changes you make to the documentation source files will be automatically formatted when you commit them with Git. This ensures that commits contain only related changes, and no extra formatting.
If you'd like to check whether your changes are formatted correctly, or format them before committing, you can run Prettier manually from the command line.
npm run check
npm run format