Getting Started Tutorial

Getting Started with DocBuilder

This tutorial walks you through producing a multi‑repository Hugo documentation site in minutes.

Prerequisites

  • Go toolchain (>=1.21) installed.
  • Hugo installed (optional unless you want automatic static rendering).
  • Git access tokens / SSH keys for the repositories you want to aggregate.

1. Install / Build

1
2

make build
# Result: ./bin/docbuilder

2. Initialize Configuration

1

./bin/docbuilder init -c config.yaml

This creates a starter config.yaml you can customize.

3. Add Repositories

Edit config.yaml and list repositories:

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

repositories:
  - url: https://git.example.com/org/service-a.git
    name: service-a
    branch: main
    paths: [docs]
    auth:
      type: token
      token: ${GIT_ACCESS_TOKEN}
  - url: https://git.example.com/org/monorepo.git
    name: monorepo
    branch: main
    paths: [docs, documentation/guides]
    auth:
      type: token
      token: ${GIT_ACCESS_TOKEN}
output:
  directory: ./site
  clean: true

4. Run a Build

1

./bin/docbuilder build -c config.yaml -v

On success you’ll have:

  • site/hugo.yaml (generated Hugo config)
  • site/content/<repo>/... (or content/<forge>/<repo>/... if multi‑forge)
  • Optional site/public/ if Hugo rendering enabled
  • site/build-report.json with metrics (doc_files_hash fingerprint)

5. Serve (Optional)

If you enabled Hugo rendering (for example with --render-mode always), serve the generated site directly:

1

hugo server -s site

Or run Hugo manually afterwards:

1

(cd site && hugo)

6. Incremental Workflow

Enable incremental builds to skip unchanged repositories:

1
2
3
4

build:
  enable_incremental: true
  cache_dir: .docbuilder-cache
  clone_strategy: auto  # Reuse existing clones

On subsequent runs, DocBuilder will:

  • Check cached build manifests
  • Skip builds if inputs haven’t changed
  • Significantly speed up CI pipelines

7. Multi-Version Documentation (Optional)

To build documentation from multiple branches/tags:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

versioning:
  enabled: true
  strategy: branches_and_tags
  max_versions_per_repo: 5
  tag_patterns:
    - "v*"           # Semantic versions
    - "[0-9]*"       # Numeric tags
  branch_patterns:
    - "main"
    - "develop"

This will:

  • Discover all matching branches/tags
  • Clone each version separately
  • Generate version-specific content paths
  • Create Hugo config with version metadata
1
2
3

build:
  clone_strategy: auto
  shallow_depth: 5

Re-run:

1

./bin/docbuilder build -c config.yaml -v

You’ll see logs about unchanged repository heads and (when applicable) an unchanged documentation set.

7. Next Steps

  • Customize landing pages with templates/index/*.tmpl.
  • Pick a supported theme (hextra, docsy, or relearn).
  • Integrate with CI: compare doc_files_hash between runs to skip downstream jobs.

You are ready to explore How‑To guides for specific tasks.