Building Oxygen XML WebHelp Output on Travis CI

This topic assumes you have a DITA project hosted on a GitHub public or private repository.

The goal of this tutorial is to help you setup a Travis continuous integration job that automatically publishes your DITA project to GitHub pages after every commit. The published website will contain a feedback link on each page that would allow a contributor to easily suggest changes to the documentation by creating a pull request on GitHub with just a few clicks.

Enable the Travis CI Build

  1. Sign in to Travis CI with your GitHub account, accepting the GitHub access permissions confirmation.
  2. Once you are signed in, and you have synchronized your GitHub repositories, go to your profile page and enable Travis CI for the repository you want to build.

Configure the Travis CI Build in your GitHub Project

  1. Checkout your GitHub project locally.
  2. Copy the .travis folder from here to the root directory of your project.
  3. In the root of your GitHub project, add a file called .travis.yml with the following content:
    language: dita
      - echo "Installed"
      - sh .travis/
      - sh .travis/
        - DITAMAP=/path/to/your/ditamap/file
        - DITAVAL=/path/to/your/ditaval/file
        - ANT_OPTS=-Xmx1024M
    Note: Replace /path/to/your/ditamap/file and /path/to/your/ditaval/file with the appropriate paths to your DITA map and ditaval files.
  4. Create a GitHub personal access token by following this procedure.
  5. Define an environment variable in the repository settings that has the name GH_TOKEN and the value equal with the GitHub personal access token created earlier.

Register Your License Key

  1. Edit your .gitignore file (or create it if it does not already exist) and add the following line:
  2. Copy your WebHelp license to the root of your GitHub project in a file called licenseKey.txt.
    Important: The licenseKey.txt file should not be committed to GitHub as it contains a license key that is issued only to you.
  3. Encrypt the license key file and add it to the .travis.yml configuration file. This way only the Travis CI server will be able to decrypt it during the build process.

Commit to GitHub

  1. Commit the following files and folders and push the commit to GitHub:
    git add .gitignore licenseKey.txt.enc .travis.yml .travis/
    git commit -m "Set up the Travis CI publishing system"
    git push
  2. Create a gh-pages branch in your GitHub project where the WebHelp output will be published. You can follow the procedure here.