Solutions to Common Problems

If you are stuck, also check Stack Overflow or raise an issue on GitHub.

References

Q: How can I reference source code from my documentation?

Answer

Within your documents folder (default src/docs), use relative includes:

include::filename.adoc[]

For files outside the documents folder, use:

include::/home/runner/work/docToolchain/docToolchainfilename.adoc[]

To make this work in editor previews, add:

ifndef::projectRootDir[:projectRootDir: ../../../]

Images

Q: Why are images not shown in the preview of my editor?

Answer

Your editor does not know the imagesdir attribute. Add this line to each file:

ifndef::imagesdir[:imagesdir: ../images]

Q: Which image format should I use?

Answer

PNG is the preferred format — all output formats support it well.

Other formats:

SVG

Great for high-resolution diagrams but may not render correctly in DOCX output.

JPG

Good for photos, not for diagrams (compression artifacts).

GIF

Not supported by the PDF renderer.

Q: Why are my images rotated in the output?

Answer

Mobile devices store orientation in image metadata rather than rotating the image. Fix with ImageMagick: convert -auto-orient photo.jpg photo.jpg Or re-save the image in any editor.

Runtime

Q: I get Could not initialize class java.awt.GraphicsEnvironment in WSL

Answer

This is a known WSL issue related to PlantUML and font rendering.

Solutions (try in order):

  1. Shut down WSL: wsl --shutdown from PowerShell, then retry

  2. Reinstall your Java runtime

  3. Use PowerShell instead of WSL

  4. Use a Kroki server for diagram rendering instead of PlantUML

Make sure WSL is up-to-date: wsl --update

Q: How do I configure a proxy?

Answer

Pass proxy settings as system properties:

./dtcw4 local generateSite -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=3128

Q: Can I tune the JVM startup for faster v4 builds?

Answer

docToolchain v4 runs every task in a fresh, short-lived JVM (no Gradle daemon). To make that startup cheap, the dtcw wrapper launches the v4 JVM with these flags by default: -XX:TieredStopAtLevel=1 -XX:+UseSerialGC.

A run that lasts only seconds never recoups the cost of the C2 JIT compiler optimising hot methods it abandons moments later. Capping the JIT at level 1 (C1) removes that wasted compilation, and SerialGC skips parallel-GC thread setup. On a typical site this roughly halves the wall-clock time.

The flags are a default, not a hard-coded value. Override them with the DTC_JAVA_STARTUP_OPTS environment variable:

# Disable the defaults entirely:
DTC_JAVA_STARTUP_OPTS= ./dtcw4 local generateSite

# Replace them with your own choice:
DTC_JAVA_STARTUP_OPTS="-XX:+UseParallelGC" ./dtcw4 local generateSite
Tip
 For a very large documentation set whose render runs for minutes, the C2 JIT does eventually pay off. There, disabling the defaults (DTC_JAVA_STARTUP_OPTS=) can be faster — measure both and keep the winner.