Configuration Reference

This page enumerates the primary configuration sections and fields supported by DocBuilder for both direct build and daemon modes.

Top-Level Structure

1
2
3
4
5
6

repositories: []    # List of repositories to aggregate
build: {}           # Performance & workspace tuning
daemon: {}          # Daemon mode settings (link verification, sync, storage)
versioning: {}      # Multi-version documentation (optional)
hugo: {}            # Hugo site metadata & theme
output: {}          # Output directory behavior

Repositories

Build Section

Daemon Section

Configuration for daemon mode operation, including link verification, sync scheduling, and storage paths.

Link Verification

Automated link validation using NATS for caching and event publishing. Requires NATS server with JetStream enabled.

Link Verification Examples

Basic Configuration:

1
2
3
4

daemon:
  link_verification:
    enabled: true
    nats_url: "nats://localhost:4222"

Remote NATS with Authentication:

1
2
3
4
5
6

daemon:
  link_verification:
    enabled: true
    nats_url: "nats://username:password@nats.example.com:4222"
    subject: "docbuilder.links.broken"
    kv_bucket: "prod-link-cache"

NATS Cluster Configuration:

1
2
3
4

daemon:
  link_verification:
    enabled: true
    nats_url: "nats://server1:4222,nats://server2:4222,nats://server3:4222"

TLS/Secure Connection:

1
2
3
4

daemon:
  link_verification:
    enabled: true
    nats_url: "tls://nats.example.com:4222"

Custom Verification Settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

daemon:
  link_verification:
    enabled: true
    nats_url: "nats://localhost:4222"
    cache_ttl: "48h"              # Cache successful checks for 2 days
    cache_ttl_failures: "30m"     # Recheck failures after 30 minutes
    max_concurrent: 20            # Increase parallelism
    request_timeout: "15s"        # Longer timeout for slow sites
    verify_external_only: true    # Skip internal link checks
    skip_edit_links: true         # Skip edit links (default, requires auth)

Include Edit Links in Verification:

1
2
3
4

daemon:
  link_verification:
    enabled: true
    skip_edit_links: false        # Verify edit links (will likely fail without auth)

Disable Link Verification:

1
2
3

daemon:
  link_verification:
    enabled: false

NATS Requirements

Link verification requires NATS with JetStream enabled:

1
2
3
4
5
6
7

nats-server -js

jetstream {
    store_dir: /var/lib/nats
    max_memory_store: 1GB
    max_file_store: 10GB
}

Sync Configuration

Storage Configuration

Daemon Configuration Example

1
2
3
4
5
6
7
8
9

daemon:
  link_verification:
    enabled: true
    nats_url: "nats://localhost:4222"
    cache_ttl: "24h"
  sync:
    schedule: "*/10 * * * *"  # Sync every 10 minutes
  storage:
    repo_cache_dir: "./daemon-data/repos"

Versioning Section

Enables multi-version documentation by discovering and building multiple branches/tags from each repository.

Versioning Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

versioning:
  enabled: true
  strategy: branches_and_tags
  max_versions_per_repo: 5
  tag_patterns:
    - \"v*\"           # Match semantic versions
    - \"[0-9]*\"       # Match numeric tags
  branch_patterns:
    - \"main\"
    - \"develop\"
    - \"release/*\"

With versioning enabled, DocBuilder:

• Discovers available branches/tags from each repository
• Expands each repository into multiple versioned builds
• Clones each version separately (branches use refs/heads/, tags use refs/tags/)
• Organizes content under repository-version paths
• Generates Hugo configuration with version metadata for version switchers

Hugo Section

Note: Theme selection has been removed. DocBuilder uses the Relearn theme exclusively.

Relearn Theme Parameters

Customize Relearn theme behavior via hugo.params:

1
2
3
4
5
6

hugo:
  params:
    themeVariant: "relearn-dark"
    disableSearch: false
    collapsibleMenu: true
    showVisitedLinks: true

See Use Relearn Theme for complete parameter reference.

Taxonomies

Hugo taxonomies allow you to classify and organize content. DocBuilder automatically configures the default Hugo taxonomies (tags and categories) but you can customize or extend them.

Default Configuration:

1
2
3
4

hugo:
  taxonomies:
    tag: tags
    category: categories

Custom Taxonomies:

1
2
3
4
5
6

hugo:
  taxonomies:
    tag: tags
    category: categories
    author: authors      # Custom taxonomy
    topic: topics        # Custom taxonomy

The taxonomy key (e.g., tag, author) is the singular form used in Hugo’s templates and URLs, while the value (e.g., tags, authors) is the plural form used for the collection.

Usage in Frontmatter:

Once configured, you can use taxonomies in your markdown frontmatter:

1
2
3
4
5
6
7

---
title: "My Documentation Page"
tags: ["api", "golang", "tutorial"]
categories: ["guides"]
authors: ["john-doe"]
topics: ["backend-development"]
---

DocBuilder’s FrontMatter model supports tags, categories, and keywords fields by default. Custom taxonomies can be added through the Custom field or by extending the FrontMatter structure.

Output Section

Output Directory Unification

• DocBuilder treats output.directory as the canonical output root for both direct builds and daemon mode.
• In daemon mode, daemon.storage.output_dir must match output.directory. If not provided, it is derived from output.directory.
• A validation check enforces this equality (after path normalization). Mismatches cause configuration loading to fail.
• Recommendation: set only output.directory; avoid setting daemon.storage.output_dir unless absolutely necessary.

Build Report Fields (Selected)

Environment Variable Expansion

Values like ${GIT_ACCESS_TOKEN} in YAML are expanded using the current process environment. .env and .env.local files are loaded automatically (last one wins on conflicts).

Health and Readiness Endpoints

• Endpoints are exposed on both the docs port and the admin port.
• GET /health: basic liveness endpoint; returns 200 when the server is responsive.
• GET /ready: readiness endpoint tied to render state.
  • Returns 200 only when <output.directory>/public exists.
  • Returns 503 before the first successful render or if the public folder is missing.
• When serving on the docs port, if the site is not yet rendered and the request path is /, DocBuilder returns a short 503 HTML placeholder indicating that the documentation is being prepared. This switches automatically to the rendered site once available.

Kubernetes Probes

• Probe either the docs port or the admin port. Use /ready for readiness and /health for liveness.
• Prefer probing /ready instead of the docs root /, since the root may return a temporary 503 placeholder before the first render.

Example: probe the docs port (8080)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

containers:
  - name: docbuilder
    ports:
      - containerPort: 8080 # docs
      - containerPort: 8081 # webhooks
      - containerPort: 8082 # admin
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      periodSeconds: 5
      failureThreshold: 3
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10

Example: probe the admin port (8082)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

containers:
  - name: docbuilder
    readinessProbe:
      httpGet:
        path: /ready
        port: 8082
      periodSeconds: 5
      failureThreshold: 3
    livenessProbe:
      httpGet:
        path: /health
        port: 8082
      initialDelaySeconds: 5
      periodSeconds: 10

Namespacing Behavior

When namespace_forges=auto and more than one distinct forge is present across repositories, content paths are written under content/<forge>/<repo>/.... Otherwise they remain content/<repo>/....

Skip Evaluation (Daemon Mode)

When running in daemon mode, builds are automatically skipped when nothing has changed:

1. State Tracking: Repository commits, config hash, and doc file hashes are saved after each successful build
2. Skip Rules: Validates version, config, repository commits, and content integrity
3. Automatic: Enabled by default in daemon mode (skip_if_unchanged: true)
4. CLI Mode: Not used - CLI builds always run when explicitly requested

This prevents unnecessary rebuilds when daemon polls/watches for changes but repositories haven’t been updated.

For CLI mode, simply don’t run docbuilder build if you don’t want a build. No caching is needed.

Recommendations

• Use clone_strategy: auto for most CI and daemon scenarios.
• Pin commit or module versions externally until v1.0.0 stability.
• Compare successive doc_files_hash values to drive conditional downstream jobs.