### Generated JDK 17 installation guide example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateContent.adoc

Example output from the generateContent task, showing a generated installation guide for JDK 17 using SDKMAN. The output includes sections for Windows, Mac, and Linux, each with the command 'sdk install java 17.0.1-open'.

```asciidoc
= Installing JDK 17 using SDKMAN

JDK 17 is a version of the Java Development Kit that is suitable for general use. It can be installed quickly and easily with the help of SDKMAN. This guide includes instructions for installation on Windows, Mac and Linux operating systems.

== Windows

JDK 17 can be installed on Windows with the following commands:

[source,shell]
----
sdk install java 17.0.1-open
----

== Mac

JDK 17 can be installed on Mac with the following commands:

[source,shell]
----
sdk install java 17.0.1-open
----

== Linux

JDK 17 can be installed on Linux with the following commands:

[source,shell]
----
sdk install java 17.0.1-open
----
```

--------------------------------

### Run initial setup with dtcw

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/LLM.md

Commands to install Java and docToolchain using the dtcw wrapper. Run these after downloading the wrapper.

```bash
# First install Java if needed
./dtcw local install java

# Then install docToolchain
./dtcw local install doctoolchain
```

--------------------------------

### AI: Generate installation instructions for JDK 17

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateContent.adoc

Example of using an 'AI:' block within an existing document to generate a specific section, such as installation instructions for JDK 17. The AI block is placed within the Getting Started section.

```asciidoc
== Getting Started

* Setup instructions

////
AI: Write a short how-to install JDK 17 on Windows, Mac and Linux using sdkman. Use Asciidoc syntax for the output.
////

* How to add it as a dependency
```

--------------------------------

### Generated documentation outline example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateContent.adoc

Example output from the generateContent task, showing a generated documentation outline for a fraud-detector microservice. The result includes a table of contents and sections for Overview, Getting Started, Architecture, Development, Troubleshooting, and FAQs.

```asciidoc
= Fraud-Detector
:toc:

== Overview
* Description of fraud-detector microservice
* Abstract view of architecture
* List of core libraries used

== Getting Started
* Setup instructions
* How to add it as a dependency
* Configuration instructions

== Architecture
* In-depth view of architecture
  * Components
  * Services
  * Data Structure

== Development
* Contribution Guidelines
* Coding Standards
* Debugging Suggestions

== Troubleshooting
* Known Issues and Solutions
* Support

== FAQs
* Common Questions and Answers
```

--------------------------------

### Start first tasks to install docToolchain locally

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/120_self-contained-dtc.adoc

Command to download and install docToolchain locally. The 'local' flag ensures Docker is ignored even if running, and 'tasks' shows all available tasks. docToolchain will ask for permission to install itself to $HOME/.doctoolchain and create a simple config file, fetching initial dependencies to $HOME/.doctoolchain/.gradle.

```bash
./dtcw local tasks
```

--------------------------------

### Install docToolchain with SDKMAN!

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Install docToolchain using the SDKMAN! package manager.

```bash
sdk install doctoolchain
```

--------------------------------

### Config fragment example for theme configuration

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/025_development/010_setup_dev_env.adoc

Create a file named configFragment.groovy in the site folder of your theme. The first line is the message shown to the user, the second line (starting with 'Example:') is the default value for the prompt, and the third line is the config item. If the value is surrounded by '##', the user will be prompted for this value and it will be replaced with the user's input; otherwise, the config item is added without a prompt.

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

--------------------------------

### Install docToolchain locally

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Execute the install command using the dtcw wrapper to set up the release in the local user environment.

```bash
./dtcw install doctoolchain
```

--------------------------------

### Install correct JDK locally

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/120_self-contained-dtc.adoc

Command to fetch and install the correct Java Development Kit (JDK) for docToolchain. The JDK will be installed to $HOME/.doctoolchain/jdk.

```bash
./dtcw local install java
```

--------------------------------

### Antora playbook.yml for arc42 template

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_downloadTemplate.adoc

Example playbook.yml to use with the experimental Antora support. Requires installing Antora, downloading the arc42 template as Antora style, and having a valid git repository with at least one commit.

```yml
site:
  title: Antora ARC42 Template
  start_page: arc42-template::index.adoc
content:
  sources:
  - url: ./
    start_path: src/docs/arc42
    branches: [HEAD]
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
asciidoc:
  attributes:
    sectanchors: true

output:
  dir: build/antora
```

--------------------------------

### Example folder structure for menu generation

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateSite.adoc

A sample directory layout showing how folder names and file attributes determine menu placement.

```text
src/docs
├── code1
│   ├── demo1.adoc
│   └── demo2.adoc
└── code3
    ├── demo3.adoc
    └── _demo4.adoc
```

--------------------------------

### Navigation Folder Structure Example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateSite.adoc

An example of a directory structure that determines the top-level menu and sidebar navigation hierarchy.

```text
src/docs/
├── 10_foo
│   ├── 10_first.adoc
│   └── 20_second.adoc
└── 20_bar
    ├── 10_lorem.adoc
    ├── 20_ipsum
    │   ├── 10_topic-A.adoc
    │   └── 20_topic-B.adoc
    └── 30_delis
        ├── 10_one.adoc
        ├── 20_two.adoc
        └── index.adoc
```

--------------------------------

### Install dtcw on Windows with PowerShell

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Download the PowerShell wrapper script for Windows environments.

```powershell
cd <your project>
Invoke-WebRequest doctoolchain.org/dtcw.ps1 -Outfile dtcw.ps1
```

--------------------------------

### Configure searchPath

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_exportEA.adoc

Example of setting the docDir and searchPath parameters to define where Enterprise Architect project files are searched.

```groovy
docDir = 'D:\work\mydoc\' ; exportPath = 'src/projects'
```

--------------------------------

### Start and Verify Local Kroki Server

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/170_kroki-configuration.adoc

Commands to launch a local Kroki container and verify its health status.

```bash
docker run -d --name kroki -p 8000:8000 yuzutech/kroki
```

```bash
curl http://localhost:8000/health
```

--------------------------------

### Install docToolchain with dtcw on MacOS/Linux/WSL2

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Commands to install docToolchain and Java using the dtcw wrapper script on Unix-like systems.

```bash
./dtcw install doctoolchain
```

```bash
./dtcw install java
```

--------------------------------

### Configure exportPath

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_exportEA.adoc

Example of setting the docDir and exportPath parameters to define where diagrams and notes are exported.

```groovy
docDir = 'D:\work\mydoc\' ; exportPath = 'src/pdocs'
```

--------------------------------

### Get Java via dtcw

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/070_publishToConfluence.adoc

Command to install Java using the docToolchain wrapper, used when docToolchain is not available as a Docker image.

```console
$ ./dtcw getJava
```

--------------------------------

### Create project directory and download dtcw wrapper

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/070_publishToConfluence.adoc

Commands to create a demo directory and download the docToolchain wrapper script from doctoolchain.org.

```console
$ mkdir publishToConfluenceDemo
$ cd publishToConfluenceDemo
$ curl -Lo dtcw doctoolchain.org/dtcw
```

--------------------------------

### GraphViz Diagram Example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/170_kroki-configuration.adoc

Example of a GraphViz diagram definition for docToolchain.

```asciidoc
[graphviz]
....
digraph G {
    rankdir=LR;
    node [shape=box, style=rounded];
    
    "Local Tools" -> "asciidoctor-diagram";
    "Kroki Server" -> "asciidoctor-diagram";
    "Kroki Server" -> "asciidoctor-kroki";
    
    "asciidoctor-diagram" -> "docToolchain";
    "asciidoctor-kroki" -> "docToolchain";
    
    "docToolchain" -> "Beautiful Docs";
}
....
```

--------------------------------

### Mermaid Flowchart Example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/170_kroki-configuration.adoc

Example of a Mermaid flowchart definition for docToolchain.

```asciidoc
[mermaid]
....
graph TD
    A[AsciiDoc Document] --> B{Extension Type?}
    B -->|asciidoctor-diagram| C[diagram-server-url]
    B -->|asciidoctor-kroki| D[kroki-server-url]
    C --> E[Kroki Server]
    D --> E
    E --> F[Rendered Diagram]
....
```

--------------------------------

### Automatic config creation with -PcreateConfig=true

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/30_config.adoc

Use the -PcreateConfig=true project property to explicitly request automatic config creation without enabling full headless mode.

```bash
./dtcw generateHTML -PcreateConfig=true
```

--------------------------------

### Run doctoolchain to generate HTML

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/template_config/doctoolchain_demo.adoc

Starts a first conversion to HTML. The results are written to <docDir>/build. If the command is not found, add <doctoolchainDir>/bin to your PATH or run the command as <doctoolchainDir>/bin/doctoolchain ...

```shell
doctoolchain <docDir> generateHTML
```

--------------------------------

### PlantUML Sequence Diagram Example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/170_kroki-configuration.adoc

Example of a PlantUML sequence diagram definition for docToolchain.

```asciidoc
[plantuml]
....
@startuml
actor User
participant "docToolchain" as DTC
participant "Kroki Server" as Kroki
participant "PlantUML" as PUML

User -> DTC: generateHTML
DTC -> Kroki: POST diagram source
Kroki -> PUML: render diagram
PUML -> Kroki: SVG/PNG
Kroki -> DTC: diagram image
DTC -> User: HTML with diagram
@enduml
....
```

--------------------------------

### Run doctoolchain to generate PDF

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/template_config/doctoolchain_demo.adoc

Starts a first conversion to PDF. The results are written to <docDir>/build. If the command is not found, add <doctoolchainDir>/bin to your PATH or run the command as <doctoolchainDir>/bin/doctoolchain ...

```shell
doctoolchain <docDir> generatePDF
```

--------------------------------

### docToolchain project initialization and documentation generation workflow

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/LLM.md

Complete bash workflow for setting up a docToolchain project: creates a directory, downloads the dtcw wrapper, initializes with the arc42 template, generates HTML and PDF, and verifies output directories. Use this as a starting point for typical projects.

```bash
# Initialize a project
mkdir my-documentation
cd my-documentation

# Download wrapper
curl -Lo dtcw https://doctoolchain.org/dtcw
chmod +x dtcw

# Initialize with arc42 template
./dtcw downloadTemplate

# Generate HTML
./dtcw generateHTML

# Generate PDF
./dtcw generatePDF

# Check output
ls -la build/docs/html5
ls -la build/docs/pdf
```

--------------------------------

### docToolchainConfig.groovy configuration example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/LLM.md

Sample configuration for docToolchain, setting outputPath, inputPath, inputFiles, and imageDirs. This is the basic configuration file created in the project directory.

```groovy
// Output path for generated documents
outputPath = 'build/docs'

// Path where docToolchain will search for input files
inputPath = 'src/docs'

// Files to process and output formats
inputFiles = [
    [file: 'arc42/arc42.adoc', formats: ['html','pdf']],
    // Add more files as needed
]

// Directories containing images
imageDirs = ["${inputPath}/images"]
```

--------------------------------

### Install docToolchain with dtcw on Windows cmd.exe

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Commands to install docToolchain and Java using the dtcw.bat wrapper script on Windows.

```bash
./dtcw.bat install doctoolchain
```

```powershell
.\dtcw.bat install java
```

--------------------------------

### Install docToolchain with dtcw on Windows PowerShell

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Commands to install docToolchain and Java using the dtcw.ps1 wrapper script on Windows.

```bash
./dtcw.ps1 install doctoolchain
```

```powershell
.\dtcw.ps1 install java
```

--------------------------------

### Create presentation.adoc and download image

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/110_presentations_with_revealjs.adoc

Creates a minimal AsciiDoc presentation file with slides and an image, then downloads the Debian logo image.

```shell
$ mkdir -p src/images
$ cat << EOF >> src/presentation.adoc
= Title Slide

== Slide 1

* This is the first slide

== Slide 2

* This is the second slide

== Slide with Image

* The Debian Logo

image::debian.svg[]
EOF

$ curl -Lo src/images/debian-logo.svg https://www.debian.org/logos/openlogo.svg
```

--------------------------------

### Configure inputFiles for generateContent

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateContent.adoc

Example configuration specifying input files for the generateContent task. The inputFiles list includes a file entry with formats for HTML, PDF, and DocBook.

```groovy
/** config redacted **/
inputFiles = [
	[file: 'example/example.adoc', formats: ['html','pdf', 'docbook']],
        /** inputFiles **/
]
/** config redacted  **/
```

--------------------------------

### Install CI Dependencies

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/CLAUDE.md

Installs required system dependencies for the CI environment, including Graphviz, ShellCheck, Pandoc, and PowerShell.

```bash
sudo apt-get install -y graphviz shellcheck pandoc powershell
```

--------------------------------

### Exported file attributes example

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_exportContributors.adoc

Example of the file attributes exported by the exportContributors task and stored in {targetDir}/fileattribs/{filename}. These attributes include lastUpdated, lastAuthorName, lastAuthorEmail, lastAuthorAvatar, and lastMessage.

```asciidoc
:lastUpdated: 16.05.2019 06:22
:lastAuthorName: Ralf D. Müller
:lastAuthorEmail: ralf.d.mueller@gmail.com
:lastAuthorAvatar: http://www.gravatar.com/avatar/cc5f3bf8b3cb91c985ed4fd046aa451d?d=identicon[32,32,role='gravatar',alt='Ralf D. Müller',title='Ralf D. Müller']
:lastMessage: #310 started to document config options
```

--------------------------------

### Initialize git repository

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/110_presentations_with_revealjs.adoc

Initializes a git repository, adds .gitignore entries for generated files, and makes an initial commit.

```shell
$ git init

# Ignore generated files in your git repository
$ echo ".gradle" > .gitignore
$ echo "build" >> .gitignore
$ git add .gitignore

$ git commit -m "Initial commit for my reveal.js slide deck"
```

--------------------------------

### Run first docToolchain command

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/010_manual/20_install.adoc

Execute the tasks command to list available docToolchain tasks and initialize dependencies.

```bash
./dtcw tasks --group=doctoolchain
dtcw 0.50 - 8061694f
docToolchain 2.3.0
Available docToolchain environments: local <.>
Environments with docToolchain [2.3.0]: local <.>
Using environment: local <.>
Using Java 17.0.6 [/home/john_doe/.doctoolchain/jdk/bin/java] <.>
Downloading https://services.gradle.org/distributions/gradle-7.5.1-bin.zip <.>
..........10%..........20%..........30%...........40%..........50%..........60%..........70%...........80%..........90%..........100%

Welcome to Gradle 7.5.1!

Here are the highlights of this release:
 - Support for Java 18
 - Support for building with Groovy 4
 - Much more responsive continuous builds
 - Improved diagnostics for dependency resolution

For more details see https://docs.gradle.org/7.5.1/release-notes.html

To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/7.5.1/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Configure project :

Config file '/code/docToolchainConfig.groovy' does not exist' <.>
[ant:input]
[ant:input] do you want me to create a default one for you? (y, n)
y
```

--------------------------------

### Configure diagramFilter

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_exportEA.adoc

Example of setting the diagramFilter parameter to filter diagrams by tag.

```groovy
diagramFilter = "myProject1, myProject2"
```

--------------------------------

### Example output of generateHTML

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/020_tutorial/030_generateHTML.adoc

The console output displayed when running the generateHTML task.

```shell session
$ ./dtcw generateHTML
dtcw - docToolchain wrapper V0.23
docToolchain V2.0.0

Bash is running on WSL
this might cause problems with plantUML
see https://doctoolchain.github.io/docToolchain/#wsl for more details

Java Version 11
docker available
home folder exists
use local homefolder install /home/rdmueller/.doctoolchain/
Starting a Gradle Daemon, 22 busy Daemons could not be reused, use --status for details

> Configure project :
arc42/arc42.adoc

> Task :generateHTML
Converting /c/Users/ralfd/projects/dtc-tests/wsl/src/docs/arc42/arc42.adoc

BUILD SUCCESSFUL in 26s
1 actionable task: 1 executed
```

--------------------------------

### Sample output of wipeConfluenceSpace confirmation prompt

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_wipeConfluenceSpace.adoc

Example output showing the Gradle daemon message and the interactive confirmation prompt asking to delete all pages in the space. The user must enter 'y' to confirm.

```bash
...
To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/8.1.1/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Task :wipeConfluenceSpace
[ant:input] Do you really want to delete all pages in myDemoSpace (y, n)
```

--------------------------------

### PlantUML diagram with scale attribute

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateHTML.adoc

Rendered diagram example specifying a scale of 0.75.

```asciidoc
.example diagram (with specified scale)
[plantuml,target="{plantUMLDir}demoPlantUMLScale",format=png,scale=0.75]
----
!pragma layout smetana
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
----
```

--------------------------------

### PlantUML diagram rendering

Source: https://github.com/doctoolchain/doctoolchain/blob/ng/src/docs/015_tasks/03_task_generateHTML.adoc

A rendered example of a PlantUML diagram using the smetana layout.

```asciidoc
.example diagram
[plantuml,"{plantUMLDir}demoPlantUML",png]
----
!pragma layout smetana
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
----
```