dita-ot/docs

DITA Open Toolkit documentation

DITA Open Toolkit Docs

This repository tracks the documentation source files for the DITA Open Toolkit project.

• Building the documentation output
• Building with development versions of DITA Open Toolkit
• Contribution guidelines
• Installing formatting tools
• Running Prettier

Building the documentation output

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.

Prerequisites

You must have a JRE and a local installation of DITA-OT. There is no need to download and install Gradle.

Steps

1. Open a command prompt, and change to the directory of your docs repository clone.

2. 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
     

Alternative: 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:

1. In the root directory of your dita-ot repository, run Gradle to compile the Java code and install plugins.

   • On Linux, macOS, or Git Bash, use ./gradlew.
   • On Windows, use gradlew.bat.

2. Then run the Gradle build in the docs repository to generate topics and build the documentation output.

   • On Linux, macOS, or Git Bash, run the build script like this:

     ./gradlew -PditaHome=../dita-ot/src/main
     

   • On Windows, use gradlew.bat:

     gradlew.bat -PditaHome=C:\path\to\dita-ot\src\main
     

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

Results

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.)

Building with development versions of DITA Open Toolkit

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.

Contribution guidelines

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:

• Test before committing
• Commit related changes
• Commit often
• Write good commit messages
• Sign your work

Installing formatting tools

The documentation repository uses the following JavaScript tools to keep source files consistently formatted:

• 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.

Prerequisites

• You must have a stand-alone installation of Git from git-scm.com/downloads.
• Include the Git installation location in the PATH environment variable.

Steps

To set these tools up:

1. Install Node.js® from nodejs.org
2. Open a command prompt, and change to the directory of your docs repository clone.
3. Run 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.

Troubleshooting

If the 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"

Solution: Uninstall Husky via npm husky uninstall. Install Git. Add the installation location to the PATH environment variable. Re-run npm install.

Running Prettier

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.

Check formatting

npm run check

Format all files

npm run format