- Building the documentation output
- Building with development versions of DITA Open Toolkit
- Contribution guidelines
- Installing formatting tools
- Running Prettier
Building the documentation output
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.
Open a command prompt, and change to the directory of your docs repository clone.
Type a variant of the following command for your operating system, adjust the path to your DITA-OT installation, and press Enter:
On Linux or macOS, use
On Windows, use
Using a `dita-ot` repository clone
If you’re using a clone of the DITA-OT development repository as your toolkit installation alongside your clone of the docs repository, run the build script on Linux or macOS like this:
You can also specify a single output format. To build HTML output, enter the following on the command line:
./gradlew -PditaHome=../dita-ot/src/main html
If all goes well, you receive a "BUILD SUCCESSFUL" message, and the generated DITA topics are written to the
parameters directories in the
out folder of the
This folder is created automatically if it doesn’t exist. (Git ignores the contents so you don’t inadvertently commit these transient output files.)
Building with development versions of DITA Open Toolkit
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
We welcome contributions to the DITA-OT documentation. Please review the guidelines for contributing to this repository before creating issues or opening pull requests.
- Test before committing
- Commit related changes
- Commit often
- Write good commit messages
- Sign your work
Installing formatting tools
- Prettier is an opinionated code formatter that enforces a consistent style by parsing code and re-printing it.
- Husky uses Git hooks to ensure that Prettier runs on all staged changes to format files before committing.
- You must have a stand-alone installation of Git from git-scm.com/downloads.
- Include the Git installation location in the
To set these tools up:
- Install Node.js® from nodejs.org
- Open a command prompt, and change to the directory of your docs repository clone.
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.
git command is not available in your command-line environment, the Husky installation may fail with an error message:
"Cannot read property 'toString' of null"
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
Format all files
npm run format