Documentation Aggregation Configuration Reference

Complete reference for configuring the documentation aggregation system.

Configuration Files

repos-config.json

Main configuration file for production aggregation. Uses git URLs and commit locks.

Location: Project root

repos-config.local.json

Development configuration file for local testing. Uses file:// URLs to avoid git operations.

Location: Project root

Configuration Structure

{
  "repos": [
    {
      "name": "repository-name",
      "url": "https://github.com/org/repo",
      "docs_path": "docs",
      "ref": "main",
      "commit": "abc123...",
      "root_files": ["README.md"],
      "structure": "flat",
      "media_directories": [".media", "assets"]
    }
  ]
}

Field Reference

Required Fields

name

• Type: String
• Description: Unique identifier for the repository
• Example: "gardenlinux", "builder", "python-gardenlinux-lib"
• Notes: Used in generated paths and logging

url

• Type: String (URL or file path)
• Description: Repository location
• Examples:
  • Git: "https://github.com/gardenlinux/gardenlinux"
  • Local: "file://../gardenlinux"
• Notes: For local development, use file:// URLs in repos-config.local.json

docs_path

• Type: String
• Description: Path to documentation directory within the repository
• Examples: "docs", "documentation", "." (for root)
• Default: "docs"
• Required: Yes — set explicitly for every repository in repos-config.json
• Notes: Relative to repository root; content of this directory is copied. The documentation CI also derives the repository's documentation-relevant paths from docs_path and root_files (see docs_paths)

ref

• Type: String
• Description: Git reference to fetch (branch, tag, or commit)
• Examples: "main", "v1.0.0"
• Notes: Required for git URLs; ignored for file:// URLs

Optional Fields

commit

• Type: String (commit hash)
• Description: Lock to a specific commit for reproducible builds
• Example: "abc123def456..."
• Default: Not used (fetches from ref)
• Notes: Generated automatically with make aggregate-update

root_files

• Type: Array of strings
• Description: Root-level files to copy (e.g., README.md, CONTRIBUTING.md)
• Example: ["README.md", "CONTRIBUTING.md", "LICENSE"]
• Default: [] (no root files copied)
• Notes: Files can have github_target_path front-matter for targeted placement. These files are also treated as documentation-relevant by the documentation CI (see docs_paths)

docs_paths

• Type: Array of strings (glob patterns)
• Description: Explicit override for the documentation-relevant paths used by the documentation CI to decide whether a pull request touched documentation
• Example: ["docs/**", "README.md", "DEVELOPER.md"]
• Default: Derived as ["<docs_path>/**", ...root_files]
• Notes: Only needed when a repository's documentation paths differ from the derived default (e.g. daily, which also ships README.md/DEVELOPER.md). Patterns use * for a single path segment and ** for any depth

structure

• Type: String
• Description: How to reorganize directory structure
• Options:
  • "flat" — Copy all files as-is
  • "sphinx" — Sphinx documentation structure
• Default: "flat"

media_directories

• Type: Array of strings
• Description: Directory names to treat as media/assets
• Example: [".media", "assets", "_static", "images"]
• Default: [".media", "assets"]
• Notes:
  • Searched recursively in source repository
  • Nested media dirs (e.g., tutorials/assets/) copied to same relative path
  • Root-level media dirs (e.g., _static/) copied to common ancestor of targeted files

Complete Example

{
  "repos": [
    {
      "name": "gardenlinux",
      "url": "https://github.com/gardenlinux/gardenlinux",
      "docs_path": "docs",
      "ref": "main",
      "commit": "c4b1d8d7f878fcb3e779315d28e35fcb19ae4dfb",
      "root_files": ["CONTRIBUTING.md", "SECURITY.md"]
    },
    {
      "name": "builder",
      "url": "https://github.com/gardenlinux/builder",
      "docs_path": "docs",
      "ref": "main",
      "commit": "b10476ad8c46130f310e36daa42c6e2c14fb51a9"
    },
    {
      "name": "python-gardenlinux-lib",
      "url": "https://github.com/gardenlinux/python-gardenlinux-lib",
      "docs_path": "docs",
      "ref": "main",
      "commit": "9142fccc3d83ab51759db7d328fa19166bc1df63",
      "structure": "sphinx",
      "target_map": {
        "cli.md": "reference/python-gardenlinux-lib-cli.md",
        "api.md": "reference/python-gardenlinux-lib-api.md"
      }
    }
  ]
}

Environment-Specific Configuration

Production (repos-config.json)

• Use HTTPS git URLs
• Include commit locks for reproducibility
• Use stable branches for ref

Development (repos-config.local.json)

• Use file:// URLs for local repos
• Omit commit field (not used for local)
• Omit ref field (not needed for file://)
• Keep structure and other settings consistent with production

Example local config:

{
  "repos": [
    {
      "name": "gardenlinux",
      "url": "file://../gardenlinux",
      "root_files": ["CONTRIBUTING.md", "SECURITY.md"]
    }
  ]
}

Common Configuration Patterns

Minimal Configuration

Simplest configuration for a flat repository:

{
  "name": "my-repo",
  "url": "https://github.com/org/my-repo",
  "docs_path": "docs",
  "ref": "main"
}

With Targeted Documentation

Repository using github_target_path front-matter:

{
  "name": "my-repo",
  "url": "https://github.com/org/my-repo",
  "ref": "main",
  "media_directories": ["assets", "_static"]
}

Then in your markdown files:

---
title: "My Tutorial"
github_target_path: "docs/tutorials/my-tutorial.md"
---

Front-Matter Fields

Aggregation-Specific Fields

When using github_target_path for aggregated content, you can include additional metadata:

• github_instance: Base URL of the GitHub instance (default: "https://github.com").
• github_org: Organization name (e.g., "gardenlinux")
• github_repo: Repository name (e.g., "gardenlinux")
• github_source_path: Original file path in source repo (e.g., "docs/tutorial.md")
• github_branch: Branch name for edit links (default: "main")

These fields enable "Edit this page on GitHub" links for aggregated content.

Page Display Fields

For general page display and component configuration fields (such as title, description, order, overviewDescriptions, and related_topics), see VitePress Features.

Related Topics

• Documentation WorkflowHow to Contribute Documentation to Garden Linux
• Documentation Quality MarkersWriting Good Documentation
• Documentation Aggregation ArchitectureHow the documentation aggregation system works
• Adding Repositories to Documentation AggregationGuide for adding new repositories to the documentation aggregation system
• Contributing to the Garden Linux DocumentationLearn how to contribute to Garden Linux documentation — working with the aggregation system locally
• Documentation CI ArchitectureHow the GitHub Actions workflows across docs and aggregated repositories work together to validate, preview, and publish documentation
• Documentation CI Workflows ReferencePer-workflow reference for the GitHub Actions workflows that drive documentation validation, preview, and lock management
• Documentation Aggregation Technical ReferenceSource code documentation for the documentation aggregation system - modules, APIs, and implementation details
• Documentation Aggregation Testing GuideTest suite for documentation - unit tests, integration tests, and testing best practices
• VitePress Features and CustomizationsGuide to custom components, Mermaid diagrams, and VitePress features for documentation writers