🌱 Gardener Documentation

This repository builds the Gardener documentation site with VitePress. Most content is not authored here: it is aggregated from many upstream repositories into hugo/content/ and committed to master. For the full picture of how that works and why, see CONTENT_AGGREGATION.md. This README covers what you need to run the site and make a change.

🚀 Quick Start

Prerequisites

For the Docker-based preview (recommended):

• Docker installed and running.

For local development (make dev, make local-preview):

• Node.js v24 (matches the version used in CI and the Docker image).

• pnpm — enable it via Corepack (bundled with Node):

  corepack enable

  Corepack picks up the pinned pnpm version from package.json automatically.

Run it

make docker-preview

Then visit http://localhost:5173. 🎉

For a native run without Docker use make dev (dev server with hot reload) or make local-preview (production build, then preview).

📂 Content in a nutshell

All docs live in hugo/content/. Two kinds of file share that tree, told apart by a banner comment that post-processing injects at the top of each file:

Banner	Meaning	Edit here?
LOCAL	maintained in this repo (blog, about, community, landing page)	Yes. Edit directly.
MANAGED	recreated by the aggregation run: aggregated from an upstream repo (github_repo), an empty docforge aggregator index, or a post-processing navigation stub	No. For upstream files open a PR at the source (the banner prints its URL); for index pages change the .docforge/ manifests. CI blocks edits to upstream files here.

The distinction is by banner, not by folder. See CONTENT_AGGREGATION.md for the model, the pipeline, and the reasoning behind it.

✏️ Making a change

Route your change by what you are editing:

I want to change…	Where	Command	Made visible by
Code / theme (.vitepress/**, components, styles)	this repo	make dev	hot reload
Local content (LOCAL file)	the file under hugo/content/	make dev	hot reload
Managed content (MANAGED file)	the upstream repo it points to	open a PR there	the nightly aggregation run
Content structure (add/remove/move a source)	.docforge/*.yaml	make hugo-refresh to preview locally	the aggregation run once the manifest change is merged

You may edit a MANAGED file locally to test a change, but the fix only counts once it is merged upstream — the nightly run overwrites any local edit, and CI blocks PRs that touch MANAGED files here.

Creating a new local content file

Any markdown file you add under hugo/content/ without a github_repo or auto_generated frontmatter field is automatically LOCAL. (auto_generated: true classifies a file as MANAGED; it is a navigation stub recreated on every run.) There is nothing to register; placement in the tree determines the URL. Minimum frontmatter:

---
title: Your Page Title
---

title is the only strictly required field. Optional layout fields: description, editLink: false, prev: false / next: false, aside: false, sidebar: false. Do not add github_repo or auto_generated — those flip the file to MANAGED.

Adding a blog post

Create hugo/content/blog/YEAR/MONTH/your-post.md:

---
title: Your Awesome Blog Post
description: "A brief description of your post"
publishdate: '2025-06-24'
authors:
  - name: Your Name
    login: your-github-handle
    avatar: https://avatars.githubusercontent.com/u/<id>?v=4
tags:
  - community-event
---

🔧 Command reference

Command	Purpose
make dev	Dev server with hot reload (code + local content)
make docker-preview	Build and run the preview in Docker
make local-preview	Production build, then local preview
make build	Build the site into dist/
make post-process	Run the full post-processing pipeline
make hugo-refresh	Manifest testing only: delete managed banners, re-aggregate, post-process, stage
make vale	Lint changed content markdown with Vale
make diff-structure-master	Compare sitemap structure of working tree vs origin/master

🤝 Contributing

• For local content, edit the LOCAL files directly and open a PR here.
• For managed content, open a PR in the upstream repository the file is aggregated from (gardener/gardener, gardener/dashboard, gardener/gardenctl-v2, and others).
• For site/theme code, open a PR here against master.