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
- Happy staging!
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.
Move to the DITA-OT directory:
Fetch the submodules:
git submodule update --init --recursive
In the root directory, run the Gradle wrapper to compile the Java code and install plugins:
Install the HTML plug-in for the DITA-OT project website:
src/main/bin/dita --install https://github.com/dita-ot/org.dita-ot.html/archive/master.zip
Install prerequisite software
Check if Ruby is installed:
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.
gem install bundler
Switch to your clone of the project website repository:
Install all of the required gems from the project’s
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 http://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
bundle exec jekyll serve --livereload
Building documentation output
Switch to the
docsrcsubmodule of the local
Check out the
developbranch of the
docsrepository to update the
docsrcsubmodule pointer to the latest development state (or to another branch if you need to generate output for that):
git checkout develop
sitebuild task with the Gradle wrapper to generate the output for the project website:
The output will be generated by default in
(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 http://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
This will install various Node modules including Parcel, the web application bundler.
_js folder. You can then run the
js folder with Parcel:
npm run install
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.