Setting Up a Dev Environment

Before You Begin

When you install docToolchain, all the code is hidden in ~/.doctoolchain/. This page explains how to set up a development environment to modify and test docToolchain itself.

Using the Devcontainer

The easiest way to develop docToolchain is using the multi-repo devcontainer from the workspace root (not this repo):

# From the workspace root (parent of docToolchain/)
./start-devcontainer.sh

This provides Java 17, Go, Python, and all necessary tools.

Local Development Setup

  1. Fork https://github.com/docToolchain/docToolchain on GitHub.

  2. Clone your fork:

    git clone --branch main-4.x git@github.com:<your-user>/docToolchain.git
cd docToolchain

  3. Build the runtime JARs:

    ./gradlew packageLibs

    This creates build/lib/*.jar — the v4 runtime classpath. Copy them to lib/ for the wrapper to detect v4:

    cp -r build/lib lib

  4. Run tasks directly:

    CLASSPATH=$(find lib/ -name '*.jar' | tr '\n' ':') \
  java -DdocDir=. -DmainConfigFile=Config.groovy \
  groovy.ui.GroovyMain scripts/generateHTML.groovy

Running Tests

./gradlew core:test

See 020_run_tests.html for details.

Create or Change a Theme

How to Overwrite a Project Theme

When docToolchain builds a static website, it copies themes in this order:

  1. Internal theme → build/microsite/tmp/site

  2. External theme (if DTC_SITETHEME is set)

  3. Project theme from src/site/

To customize, place your modified files in src/site/ in your project.

How to Create a Theme from Scratch

A theme is the contents of the src/site/ directory. See the jBake documentation for the expected structure.

Special Functionality for Themes (Config Fragments)

Create a configFragment.groovy in the site folder of your theme to prompt users for config values during theme installation:

// the title of the microsite, displayed in the upper-left corner
// Example: my new site
title = '##site-title##'

Values surrounded by ## will prompt the user during installation.