Adding Repositories to Documentation Aggregation

This guide explains how to add a new repository to the documentation aggregation system.

Prerequisites

• Access to the repository you want to add
• Understanding of the repository's documentation structure
• Edit access to repos-config.json

Step 1: Add Repository Configuration

Edit repos-config.json and add a new entry to the repos array:

{
  "name": "new-repo",
  "url": "https://github.com/gardenlinux/new-repo",
  "docs_path": "docs",
  "ref": "main",
  "structure": "flat"
}

Required Fields

• name: Unique identifier for the repository
• url: Git URL or file:// path for local development
• docs_path: Path to docs directory within the repository
• ref: Git branch or tag to fetch from

Optional Fields

• commit: Lock to a specific commit hash for reproducibility
• root_files: List of root-level files to copy (e.g., ["README.md", "CONTRIBUTING.md"])
• structure: Directory mapping strategy ("flat" or "sphinx"; see below)
• media_directories: List of media directories to copy (e.g., [".media", "_static", "assets"])

Step 3: Configure Targeted Documentation

To have files automatically placed into the main Diataxis structure, add github_target_path front-matter to markdown files in the source repository:

---
title: "Example Guide"
github_target_path: "docs/how-to/example-guide.md"
---

# Example Guide

Content here...

Files with github_target_path will be copied to that exact location in the site. Source-repo files without github_target_path are excluded from the built site entirely.

Step 2: Choose a Structure Strategy

Flat Structure

Copy all docs files as-is without reorganization:

"structure": "flat"

Sphinx Structure

For Sphinx-generated documentation:

"structure": "sphinx"

Step 3: Test with Local Configuration

Create or edit repos-config.local.json for local testing:

{
  "repos": [
    {
      "name": "new-repo",
      "url": "file://../new-repo"
    }
  ]
}

Then test aggregation:

make aggregate-local

Step 4: Verify the Output

Check that targeted files landed in the correct Diataxis section:

ls -la docs/tutorials/
ls -la docs/how-to/

Step 5: Lock the Commit (Production)

For production, lock to a specific commit:

# This fetches only the new repo and updates repos-config.json with its commit hash
make aggregate-update-repo-single REPO=new-repo

Or manually add the commit hash:

{
  "name": "new-repo",
  "url": "https://github.com/gardenlinux/new-repo",
  "docs_path": "docs",
  "ref": "main",
  "commit": "abc123def456...",
  "structure": "flat"
}

Advanced Configuration

Media Directories

Automatically copy media directories alongside documentation:

{
  "name": "new-repo",
  "media_directories": [".media", "assets", "_static"]
}

The system will:

• Find all instances of these directories recursively
• Copy nested media dirs (e.g., tutorials/assets/) to the same relative path
• Copy root-level media dirs (e.g., _static/) to the common ancestor of targeted files

Root Files

Copy root-level files (like README.md or CONTRIBUTING.md):

{
  "name": "new-repo",
  "root_files": ["README.md", "CONTRIBUTING.md", "LICENSE"]
}

These files can also have github_target_path front-matter for targeted placement.

Complete Example

Here's a complete configuration:

{
  "name": "example-tool",
  "url": "https://github.com/gardenlinux/example-tool",
  "docs_path": "documentation",
  "ref": "docs-ng",
  "commit": "1234567890abcdef",
  "root_files": ["README.md"],
  "structure": "flat",
  "media_directories": [".media", "images"]
}

The docs_path field defaults to "docs" and may be omitted when the documentation lives in a docs/ directory.

Troubleshooting

Files Not Appearing

• Verify docs_path points to the correct directory
• Check that the repository has a docs-ng branch or adjust ref
• Ensure github_target_path front-matter is correct

Media Not Copied

• Add media directory names to media_directories
• Check that media dirs exist in the source repository

Links Broken

• The transformer attempts to rewrite links automatically
• Check that relative links in source docs are correct
• Review src/aggregation/transformer.py for link rewriting logic

Related Topics

• Documentation WorkflowHow to Contribute Documentation to Garden Linux
• Documentation Quality MarkersWriting Good Documentation
• Documentation Aggregation ArchitectureDeep dive into how the documentation aggregation system works
• 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-ng and aggregated repositories work together to validate, preview, and publish documentation
• Documentation CI Workflows ReferencePer-workflow reference for the four GitHub Actions workflows that drive documentation validation, preview, and lock management
• Documentation Aggregation Configuration ReferenceComplete reference for repos-config.json and repos-config.local.json configuration options
• 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