DITA Open Toolkit docs

I contribute to the DITA Open Toolkit as a collaborator and have served as the documentation lead since the version 2.0 release at DITA Europe / DITA-OT Day 2014.

DITA-OT is an open-source publishing engine for content authored in the Darwin Information Typing Architecture. Many of the best-known XML editors, enterprise authoring solutions and commercial content management systems rely on DITA-OT to publish XML content.

With over a thousand commits to the documentation in the past three years, I contribute to the project on a regular basis and communicate closely with the core committers to keep up with recent changes to the toolkit.

The site Colophon explains how we build and maintain the DITA Open Toolkit project website:

The DITA-OT project website is hosted on Netlify and deployed to dita-ot.org.

The website is maintained in Git and updated by pushing to the repository at github.com/dita-ot/website.

Source files for the project website are stored in Markdown and HTML, enriched with Liquid templating tags and styled with Sass. The Bootstrap framework provides the foundation for the site layout. The Jekyll publishing engine combines these plain text components to the final static website you see here.

The Documentation section is maintained in DITA using the source files from the DITA Open Toolkit documentation repository at github.com/dita-ot/docs. The OT docs are transformed to HTML5 using the org.dita-ot.html plugin, which extends the default html5 transformation with additional processing specific to the project website.

Site output is built with Gradle using the settings in the site build task. The DITA Open Toolkit Gradle plugin is used with the Gradle dæmon and the --continuous build option to automatically regenerate the site output whenever documentation source files change. A staging environment provides a preview of generated site output via the jekyll serve command for local testing. The --livereload option updates the content in the browser whenever source files change on disk.

A continuous integration process based on GitHub Actions automatically republishes the latest development version of the documentation on the project website whenever changes are pushed to the develop branch of the dita-ot/docs repository.

Documentation and website source files are formatted with Prettier. Git hooks configured with Husky and lint-staged ensure that Prettier runs on all staged changes to format content consistently before committing.

The development docs are indexed by Algolia DocSearch, which provides the full text search capabilities available via the search form in the navigation bar.

The pages in the development documentation include Edit this page links that open the DITA source file for the topic in oXygen XML Web Author. The web-based authoring workflow prompts users to log in to GitHub and fork the dita-ot/docs repository if necessary. Changes saved in the authoring environment are committed to a new branch, and a pull request is created to submit changes for review by the DITA-OT documentation team.