title	Contributing to the Garden Linux Documentation
description	Learn how to contribute to Garden Linux documentation — working with the aggregation system locally

Contributing to the Garden Linux Documentation

Garden Linux documentation is published at https://gardenlinux-docs.netlify.app/ and combines content from multiple repositories into a unified documentation site.

Source Repository: gardenlinux/docs-ng

Working with the Documentation System Locally

For more substantial changes — like adding new pages, restructuring content, or working on the aggregation system itself — you'll want to set up the documentation system locally.

Prerequisites

• Python 3.x
• pnpm (for VitePress)
• Git

Step 1: Clone the Repository

git clone https://github.com/gardenlinux/docs-ng.git
cd docs-ng

Step 2: Install Dependencies

pnpm install

This installs VitePress and other Node.js dependencies needed to build the documentation site.

Step 3: Aggregate Documentation

From Remote Repositories (Production)

Aggregate from locked commits in repos-config.json:

make aggregate

This fetches documentation from the configured repositories at their locked commit hashes.

From Local Repositories (Development)

For local development, use repos-config.local.json with file:// URLs:

make aggregate-local

This copies documentation from local repositories without using git.

Step 4: Start the Development Server

make dev

The documentation site will be available at http://localhost:5173.

Step 5: Make Changes

As you work on documentation in source repositories:

1. Make changes to markdown files in source repos
2. Run make aggregate-local to update the aggregated docs
3. The dev server will hot-reload automatically

Step 6: Build for Production

When ready to deploy:

make build

This creates a production build in docs/.vitepress/dist/.

Common Workflows

Updating a Single Repository

make aggregate-repo REPO=gardenlinux

Updating Lock Files

To fetch the latest commits and update repos-config.json:

make aggregate-update

Running Tests

make test

Project Structure

After aggregation, your docs directory will look like:

docs/
├── projects/              # Mirrored repository docs
│   ├── gardenlinux/
│   ├── builder/
│   └── python-gardenlinux-lib/
├── tutorials/             # Aggregated tutorials
├── how-to/                # Aggregated guides
├── explanation/           # Aggregated explanations
├── reference/             # Aggregated reference
└── contributing/          # Aggregated contributing docs

Next Steps

• Learn how to add new repositories
• Understand the architecture
• Review the configuration reference

Troubleshooting

Clean Build

If you encounter issues, try a clean build:

make clean
make aggregate
make dev

Check Dependencies

Ensure all dependencies are installed:

pnpm install
python3 --version  # Should be 3.x

Verify Configuration

Check that repos-config.json or repos-config.local.json is properly configured. See the configuration reference for details.

See Also

• Documentation Workflow
• Documentation Quality Markers
• Documentation Aggregator Architecture
• How to Documentation - Adding Repos to Aggregate
• How to Documentation - Working With the Aggregator Locally
• Documentation Aggregator Technical Reference
• Documentation Aggregator Local Testing Guide
• Working with the Documentation Hub on Your Machine