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
   

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

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.