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, 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...
    enabled: true                # set false to remove the page from the portal entirely
    notes: ""                    # freeform hints passed to the synthesizer (not shown to readers)
    guidance: ""                 # optional: ground truth the AI must respect and never contradict

`guidance` — the one optional lever

Every page is AI-generated. The only decision you make per section is whether there is anything the AI needs to be told. Leave guidance blank and Git2Docs writes the page from signals in your repository — code, architecture docs, CRDs, runbooks. Add a sentence or two of guidance and the AI expands on it, never contradicting what you wrote.

You do not choose "AI" vs "human" up front. What happens when the AI can't ground a page from your code is decided automatically:

If your code grounds the page, it generates — high-confidence when the source is thorough, flagged for review when it is thin.
If the code can't ground it but you provided guidance, the AI builds the page from your guidance.
If the code can't ground it and there is no guidance, the page is left blank on purpose and marked “Needs your input” in the portal — Git2Docs never invents content it can't support. Add guidance to fill it.

This is why pages like a UI walkthrough or a partnership integration — things the code simply doesn't describe — will ask for guidance: there is nothing to ground them on.

  - id: architecture
    enabled: true
    guidance: >
      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 optional guidance.

  - id: troubleshooting
    enabled: true
    subsections:
      - id: troubleshooting_failover
        title: "Failover issues"
        description: "Diagnosing failures during planned or unplanned failover"
        enabled: true
      - id: troubleshooting_replication
        title: "Replication issues"
        description: "DRBD sync errors, split-brain detection, and lag monitoring"
        enabled: true
      - id: troubleshooting_ui
        title: "Management UI issues"
        description: "Site Manager connectivity and session problems"
        enabled: true
        guidance: >
          The management UI runs on the quorum cluster; sessions time out after 30 min.

Standard sections

These are the pages Git2Docs generates by default. Disable any that do not apply to your product. “Typically needs guidance?” flags the pages the code usually can't ground on its own — add guidance there.

Section ID	Default page title	Typically needs guidance?
`intended_audience`	Intended audience	No
`problem_statement`	Problem being solved	No
`alternatives`	Alternatives	Usually
`architecture`	Architecture	Sometimes
`key_concepts`	Key concepts	No
`getting_started`	Getting started	No
`installation`	Installation	No
`configuration`	Configuration	No
`cli_reference`	CLI reference	No
`api_reference`	API reference	No
`ui_guide`	UI guide	Usually
`automation`	Automation	No
`ecosystem_integration`	Ecosystem integration	Sometimes
`troubleshooting`	Troubleshooting	No

`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.
    enabled: true
    guidance: >
      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"
    enabled: true
    guidance: >
      Licensing is seat-based; keys are installed via the admin console.

`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
    enabled: true

  - id: problem_statement
    enabled: true

  - id: architecture
    enabled: true
    guidance: >
      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
    enabled: true

  - id: ui_guide
    enabled: true
    guidance: >
      The management UI is a web console served from the quorum cluster.

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

custom_sections:
  - id: dr_testing
    title: "DR testing"
    description: "How to run non-disruptive failover tests without impacting production."
    enabled: true
    guidance: "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

guidance — the one optional lever