GitHub Action for DITA-OT Builds

This GitHub Action installs a version of DITA Open toolkit along with any specified DITA-OT plugins and then builds a series of outputs such as a PDF document or an HTML static website.

Inputs

transtype

Name of the DITA-OT transform to run. One of build , transtype or project is required.

input

The location of the topic or ditamap to use to build the output. Defaults to document.ditamap if not supplied.

output-path

Location for the DITA-OT build outputs. Defaults to out if not supplied.

properties

A string representing any additional parameters to pass into the input.

plugins

Comma-separated list of additional DITA-OT plugins to install.

install

The name of a bash script to run to install plugins or any other dependencies prior to running the build. Script-based alternative to plugins.

project

Name of a DITA-OT project file to run as an alternative to building using a transtype. This will only run if transtype is not set.

build

Explicit command-line input or path to a bash script to run the DITA-OT build GitHub Action. This script will only run if transtype and project are left unset.

dita-ot-version

Downloads an explicit version of DITA-OT to use rather than using the default. Defaults to 4.1.

Examples

Install

Install using plugins

Installation of plugins found within the DITA-OT registry can be referred to by name. A plugin also can be referrred to using a full path if necessary.

- name: Build HTML5 using DITA-OT
  uses: dita-ot/dita-ot-action@master
  with:
      plugins : |
        https://github.com/jason-fox/fox.jason.extend.css/archive/master.zip
        org.jung.xmltask
        com.oxygenxml.json.dita
      input: document.ditamap
      transtype: html5
      output-path: out

Install using command line statements

Plugins can also be installed using the dita command.

- name: Build HTML5 using DITA-OT
  uses: dita-ot/dita-ot-action@master
  with:
      install : |
        dita install https://github.com/jason-fox/fox.jason.extend.css/archive/master.zip
        dita install org.jung.xmltask
        dita install com.oxygenxml.json.dita
      input: document.ditamap
      transtype: html5
      output-path: out

Install with additional prerequisites

The following steps install Node.js and switch the locale to German. By default, out of the box, the plugin only supports the English locale,

- name: Build HTML5 + Bootstrap
  uses: dita-ot/dita-ot-action@master
  with:
       install: |
            apt-get update -q
            export DEBIAN_FRONTEND=noninteractive
            apt-get install -qy --no-install-recommends nodejs
            nodejs -v
            locale-gen de_DE.UTF-8 
            LANG="de_DE.UTF-8"  
            LANGUAGE="de_DE:de"  
            LC_ALL="de_DE.UTF-8"
       plugins: |
            fox.jason.extend.css
            net.infotexture.dita-bootstrap
            net.infotexture.dita-bootstrap.lunr           

Install using a bash script

For complex prerequisites, an additional bash script can be added into the root of the repository

- name: Build HTML5 using DITA-OT
  uses: dita-ot/dita-ot-action@master
  with:
      install : install.sh # This is a script in the root of the repository
      input: document.ditamap
      transtype: html5
      output-path: out

Build

Build using a project file

The action supports the use of the DITA-OT Project file

- name: Build HTML5 using DITA-OT
  uses: dita-ot/dita-ot-action@master
  with:
      plugins : |
        fox.jason.extend.css
        org.jung.xmltask
        fox.jason.prismjs
      project: html.xml

Build using command line statements only

The action supports the use of the dita command

- name: Build PDF using DITA-OT commands
  uses: dita-ot/dita-ot-action@master
  with:
      install : |
        dita install fox.jason.extend.css
        dita install org.jung.xmltask
        dita install fox.jason.prismjs
      build: |
        dita -i document.ditamap -o out  -f pdf --filter=filter1.ditaval

Example usage fixed to an explicit DITA-OT version and build properties

- name: Build PDF using DITA-OT 3.5.4
  uses: dita-ot/dita-ot-action@master
  with:
      dita-ot-version: 3.5.4
      plugins: |
        org.doctales.xmltask
        fox.jason.extend.css
        fox.jason.prismjs
      input: 'docsrc/document.ditamap'
      transtype: 'pdf'
      properties: '--filter=filter1.ditaval'
      output-path: out

Post-processing

The artifacts can then be uploaded from your workflow as shown:

- name: Upload DITA
  uses: actions/upload-artifact@v2
  with:
      name: dita-artifact
      path: 'out' # The folder the action should upload.

Or deployed to GitHub Pages as shown:

- name: Deploy to GitHub Pages
  uses: JamesIves/[email protected]
  with:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    BRANCH: gh-pages # The branch the action should deploy to.
    FOLDER: out # The folder the action should deploy.

License

The scripts and documentation in this project are released under the Apache License 2.0.