Config YAML Reference

The config YAML is the single most important thing you can add to your repository. It is the editorial authority — anything you specify here overrides what Git2Docs infers from the code.

Use it to correct the product brief, control which documentation sections are generated, tell the AI what to write and what never to say, and describe your directory layout.

Without this file, Git2Docs still generates documentation — it reads your README, architecture docs, manifests, and source files to build a product brief automatically. But with it, every page becomes more accurate, more opinionated, and faster to review.

File structure

The config YAML has five top-level sections:

product:         # correct the product identity the AI inferred
sections:        # control which doc pages are generated and how
custom_sections: # add product-specific pages not in the standard set
directories:     # describe your repo layout
constraints:     # hard facts the AI must never contradict

All fields are optional. Leave any field blank and Git2Docs infers it from the repo.

`product` — correct the product identity

These fields override the product brief that Git2Docs builds automatically during comprehension. Fill in only what the AI gets wrong.

product:
  name:             "Site Recovery"
  one_liner:        "Automates VM failover across Kubernetes clusters using synchronous block replication."
  audience:         "Platform engineers managing Kubernetes disaster recovery"
  audience_level:   "intermediate"    # beginner | intermediate | expert
  deployment_model: "Three-cluster: primary, DR, quorum"

Field	What it controls
`name`	Product name used in all page titles and headings
`one_liner`	The single sentence on the home page that describes what the product does and for whom. Be specific — "replicates VM-attached PVCs" is good; "manages Kubernetes resources" is not
`audience`	Who the documentation is written for, shown in the Intended Audience page
`audience_level`	Calibrates assumed knowledge across all pages — `beginner` adds more explanation, `expert` skips fundamentals
`deployment_model`	The topology summary used in architecture pages

`sections` — control the standard doc pages

Git2Docs generates a standard set of documentation pages for every repository. The sections block lets you control each one: whether it is enabled, who writes it (AI or human), and any guidance to pass to the synthesizer.

Each section has the following fields:

sections:
  - id: problem_statement        # fixed identifier — do not change
    title: "Problem being solved" # page title shown in the portal
    description: >               # what this page covers (used internally by the AI planner)
      The operational problem this product addresses...
    source: ai                   # who writes the content: ai | human_required | ai_with_seed
    enabled: true                # set false to remove the page from the portal entirely
    notes: ""                    # freeform hints passed to the synthesizer (not shown to readers)
    seed: ""                     # (ai_with_seed only) human-written anchor the AI must respect

`source` modes

This is the most important field on each section.

ai — Git2Docs drafts the page entirely from signals it finds in your repository. This works well for any page where the answer lives in code, architecture docs, CRDs, or runbooks. If those files are thorough, the page will be high-confidence. If they are thin, the page will be low-confidence and flagged for human review.

human_required — Git2Docs skips AI generation entirely and creates a stub in the portal prompting a human to write the content. Use this for pages where the answer cannot be inferred from code: UI walkthroughs, partnership integrations, support escalation procedures, and anything involving screenshots.

ai_with_seed — You write a short anchor in the seed field and Git2Docs expands it into a full page, never contradicting what you wrote. This is the best mode for pages where the AI can do most of the work but a few sentences of ground truth are essential — for example, an architecture page where the overall structure is inferable but the specific trade-offs are not.

  - id: architecture
    source: ai_with_seed
    enabled: true
    seed: >
      The quorum cluster arbitrates failover decisions and hosts the management UI.
      It never stores application data. The primary and DR clusters each run a full
      LINSTOR stack with DRBD for synchronous block replication.

Splitting a section into subsections

Any section can be split into child pages by adding a subsections array. The parent section becomes a chapter heading; each subsection becomes its own page with its own source mode.

  - id: troubleshooting
    source: ai
    enabled: true
    subsections:
      - id: troubleshooting_failover
        title: "Failover issues"
        description: "Diagnosing failures during planned or unplanned failover"
        source: ai
        enabled: true
      - id: troubleshooting_replication
        title: "Replication issues"
        description: "DRBD sync errors, split-brain detection, and lag monitoring"
        source: ai
        enabled: true
      - id: troubleshooting_ui
        title: "Management UI issues"
        description: "Site Manager connectivity and session problems"
        source: human_required
        enabled: true

Standard sections

These are the pages Git2Docs generates by default. Disable any that do not apply to your product.

Section ID	Default page title	Default source
`intended_audience`	Intended audience	`ai`
`problem_statement`	Problem being solved	`ai`
`alternatives`	Alternatives	`ai`
`architecture`	Architecture	`ai`
`key_concepts`	Key concepts	`ai`
`getting_started`	Getting started	`ai`
`installation`	Installation	`ai`
`configuration`	Configuration	`ai`
`cli_reference`	CLI reference	`ai`
`api_reference`	API reference	`ai`
`ui_guide`	UI guide	`human_required`
`automation`	Automation	`ai`
`ecosystem_integration`	Ecosystem integration	`ai_with_seed`
`troubleshooting`	Troubleshooting	`ai`

`custom_sections` — add product-specific pages

Use custom_sections for pages specific to your product that do not belong in the standard set. They appear in the portal after the standard sections, in the order listed. All the same fields apply.

custom_sections:
  - id: dr_testing
    title: "DR testing"
    description: >
      How to run non-disruptive failover tests to validate DR readiness
      without impacting production workloads.
    source: ai_with_seed
    enabled: true
    seed: >
      DR tests use a test namespace on the DR cluster and never touch the
      primary workload. A full test takes approximately 15 minutes.

  - id: licensing
    title: "Licensing"
    description: "License key installation and seat management"
    source: human_required
    enabled: true

`directories` — describe your repo layout

Git2Docs auto-detects standard conventions for Go, Python, TypeScript, Rust, and Java. For everything else — or for repos with non-obvious structures — add directory descriptors here.

The description field is what matters. Be specific about what the code does, not just what it is. Git2Docs reads these descriptions verbatim in its comprehension prompt.

The role field tells Git2Docs how to treat each directory:

Role	Meaning
`source`	Application logic — index and document this code
`docs`	Human-written documentation — use as source material
`config`	Configuration and manifests — high-signal for architecture pages
`tests`	Test code — low signal, skip for most pages
`generated`	Auto-generated code — skip entirely
`vendor`	Third-party dependencies — skip entirely
`build`	Build artifacts — skip entirely

directories:
  - path: biz/core/engine
    description: "Main failover orchestration logic — the heart of the DR workflow"
    role: source

  - path: platform/infra/k8s
    description: "Kubernetes operator controllers and reconciliation loops"
    role: source

  - path: deploy
    description: "Helm charts, CRDs, and Kustomize overlays for all clusters"
    role: config

  - path: generated
    description: "Auto-generated client stubs — do not index for documentation"
    role: generated

Tip: You do not need to list every directory. Focus on directories whose purpose is not obvious from the name alone, and on generated/vendor directories you want explicitly excluded.

`constraints` — facts the AI must never contradict

Constraints are hard-coded truths injected into every synthesis prompt. Use them to prevent the AI from repeating a known misconception, regardless of what it infers from the code.

Write each constraint as a plain declarative sentence. They are not shown to readers.

constraints:
  - "The quorum cluster arbitrates failover — it does not store application data."
  - "DRBD replication is synchronous. Data is never lost during a clean failover."
  - "The Helm chart deploys the Site Manager UI to the quorum cluster only."
  - "Minimum supported Kubernetes version is 1.25."

Add a constraint whenever you notice the AI asserting something wrong about your product on more than one page.

Complete example

product:
  name: "Site Recovery"
  one_liner: "Automates VM failover across Kubernetes clusters using synchronous block replication."
  audience: "Platform engineers managing Kubernetes disaster recovery"
  audience_level: "intermediate"
  deployment_model: "Three-cluster: primary, DR, quorum"

sections:
  - id: intended_audience
    source: ai
    enabled: true

  - id: problem_statement
    source: ai
    enabled: true

  - id: architecture
    source: ai_with_seed
    enabled: true
    seed: >
      The quorum cluster arbitrates failover decisions and hosts the management UI.
      Primary and DR clusters each run LINSTOR with DRBD for synchronous block replication.

  - id: getting_started
    source: ai
    enabled: true

  - id: ui_guide
    source: human_required
    enabled: true

  - id: troubleshooting
    source: ai
    enabled: true
    subsections:
      - id: troubleshooting_failover
        title: "Failover issues"
        source: ai
        enabled: true
      - id: troubleshooting_replication
        title: "Replication issues"
        source: ai
        enabled: true

custom_sections:
  - id: dr_testing
    title: "DR testing"
    description: "How to run non-disruptive failover tests without impacting production."
    source: ai_with_seed
    enabled: true
    seed: "DR tests use a dedicated test namespace and never touch primary workloads."

directories:
  - path: biz/core/engine
    description: "Main failover orchestration logic"
    role: source
  - path: deploy
    description: "Helm charts and CRDs for all clusters"
    role: config
  - path: generated
    description: "Auto-generated client stubs — skip"
    role: generated

constraints:
  - "The quorum cluster arbitrates failover — it does not store application data."
  - "DRBD replication is synchronous. No data is lost during a clean failover."
  - "Minimum supported Kubernetes version is 1.25."

How the config is loaded

Git2Docs loads the config YAML at priority 0 — before any other file in the repository, including the README. Values you set here override whatever the AI infers from code or docs. The override happens in two places:

Product fields (name, one_liner, audience, audience_level, deployment_model) are applied after comprehension, replacing the AI-generated values directly.
Section configuration and constraints are injected into every synthesis prompt, shaping every page in the portal.

Changes take effect on the next documentation sync.

Config YAML Reference

File structure

product — correct the product identity

sections — control the standard doc pages

source modes