DITA Open Toolkit website

This repository contains the source files for the DITA Open Toolkit project website at dita-ot.org.

For details and background information on how we build and maintain the site, visit dita-ot.org/colophon.

If you'd like to set up a local staging environment and build a copy of the site, follow the instructions below.

• Environment setup
• Install prerequisite software
• Running Jekyll
• Building documentation output
• Updating JavaScript
• Happy staging!

Environment setup

1. Clone the DITA-OT and project website repositories:

   git clone https://github.com/dita-ot/dita-ot.git
   git clone https://github.com/dita-ot/website.git
   

   NOTE: The examples below assume the the DITA-OT and project website repositories have been cloned to a common parent directory, such as your home folder. If you clone the repositories to a different location, substitute that path for the tilde symbol ~ in the samples below.

2. Move to the DITA-OT directory:

   cd dita-ot
   

3. Fetch the submodules:

   git submodule update --init --recursive
   

4. In the root directory, run the Gradle wrapper to compile the Java code and install plugins:

   ./gradlew
   

5. Install the HTML plug-in for the DITA-OT project website: org.dita-ot.html

   src/main/bin/dita --install https://github.com/dita-ot/org.dita-ot.html/archive/master.zip
   

Install prerequisite software

1. Check if Ruby is installed:

   ruby -v
   

   Ruby is installed on macOS and most Linux distributions by default. If the command above does not respond with information on the installed Ruby version, see Installing Ruby for instructions. (Ruby 3.3 is required.)

2. Install Bundler:

   gem install bundler
   

3. Switch to your clone of the project website repository:

   cd ~/dita-ot-website
   

4. Install all of the required gems from the project’s Gemfile:

   bundle install
   

Running Jekyll

To build a copy of the site locally, use the bundle command to start the Jekyll build:

bundle exec jekyll serve

This runs the Jekyll build process and starts a local web server, so you can view your local clone of the project website at 127.0.0.1:4000.

At this stage, what you see there should be identical to the production version of the site at www.dita-ot.org.

Note: For more details, see Setting up your GitHub Pages site locally with Jekyll.

To refresh the page in your browser whenever source files change, pass the --livereload option:

bundle exec jekyll serve --livereload

Running Jekyll from Docker

Jekyll can also be run from a Docker image. No additional dependencies need to be installed:

docker run -it --rm -v $PWD:/website -e 4000 -p 4000:4000 ruby:$(head -1 .ruby-version) bash -c 'cd /website && bundle install && jekyll serve -H 0.0.0.0'

This runs a local copy of the project website at 127.0.0.1:4000.

Building documentation output

1. Switch to the docsrc submodule of the local dita-ot clone:

   cd ~/dita-ot/src/main/docsrc
   

2. Check out the develop branch of the docs repository to update the docsrc submodule pointer to the latest development state (or to another branch if you need to generate output for that):

   git checkout develop
   

3. Run the site build task with the Gradle wrapper to generate the output for the project website:

   ./gradlew site
   

The output will be generated by default in src/main/docsrc/build/site.

(This appears as unstyled HTML when viewed in place.)

To redirect the output to the dev development folder that Jekyll serves, pass the outputDir parameter to the build script as follows:

./gradlew site -PoutputDir=~/dita-ot-website/dev

After the build completes, you should find the results in the Docs > Development section of the local staging environment 127.0.0.1:4000/dev/.

To automatically regenerate the site output whenever documentation source files change, add the --continuous build option:

./gradlew site -PoutputDir=~/dita-ot-website/dev --continuous

Updating JavaScript

If you need to change any of the JavaScript files in the site repository, you'll need to download & install Node.js and run the npm package manager for JavaScript to perform a clean install of the project dependencies:

npm ci

This will install various Node modules including Parcel, the web application bundler.

To make changes to the JavaScript code, add or edit source files in the _js folder. You can then run the install script to compile the modified JavaScript code to the (ignored) js folder with Parcel:

npm run install

Happy staging!

You can now use the local staging environment to test your changes before committing your work.

When you're ready to share your progress, send us a pull request.