Building site output

This page provides instructions for setting up a local staging environment and building a copy of the project website for testing.

Environment setup — clone repositories & build the toolkit

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/dita-ot.github.io.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 — Jekyll & Gradle

1. Install & run Jekyll.

    sudo gem install jekyll
    cd ~/dita\-ot\.github\.io
    jekyll serve
   

   This runs the production version of the site locally, 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 project website at http://www.dita-ot.org.

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

2. Install Gradle.

   On Mac OS X, if you have Homebrew installed, run:

    brew install gradle
   

   Note: You only need to install Gradle if you need to generate docs output for DITA-OT versions prior to 2.3. As of DITA-OT version 2.3, the docs submodule includes a Gradle wrapper, so you can substitute ./gradlew for the gradle command that appears in the instructions below.

Building site output

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

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

2. Check out the develop branch of 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.gradle build to build the content for the project website:

    gradle -b site.gradle
   

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 output.dir parameter to the build script as follows:

gradle -b site.gradle -Doutput.dir=~/dita-ot.github.io/dev

After the build completes, you should find the results in the Documentation > 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:

gradle -b site.gradle -Doutput.dir=~/dita-ot.github.io/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 install the project dependencies:

npm install

This will install various Node modules including Gulp, the streaming build system.

To run Gulp separately, you may need to install it per http://gulpjs.com:

npm install gulp-cli -g
npm install gulp -D

You can then run Gulp to minify the modified JavaScript code:

gulp

Or run the watch-js task to monitor the JavaScript files in the project for changes, and compile the minified code whenever the source files change:

gulp watch-js

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.