Dosu Logo
Home
Documents
_index
_index
Type
External
Status
Published
Created
Mar 5, 2026
Updated
Mar 5, 2026
Source
View

This guide explains how to contribute to Porch documentation, including setting up your local environment, previewing changes, and understanding the documentation structure.

Prerequisites#

  • Git installed
  • Hugo Extended v0.110.0+ installed
  • Text editor or IDE
  • Basic familiarity with Markdown

Setup Local Environment#

Clone the Repository#

Clone using SSH (required for pushing changes):

git clone git@github.com:nephio-project/porch.git
cd porch/docs

SSH authentication links your commits to your GitHub account, which is required for CLA verification. If you haven't set up SSH keys, see GitHub's SSH documentation.

Install Hugo#

Porch documentation uses Hugo Extended edition. Install it for your platform:

macOS (Homebrew)

brew install hugo

Linux (Snap)

sudo snap install hugo

Linux (Download)

wget https://github.com/gohugoio/hugo/releases/download/v0.139.4/hugo_extended_0.139.4_linux-amd64.tar.gz
tar -xzf hugo_extended_0.139.4_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/

Windows (Chocolatey)

choco install hugo-extended

Verify installation:

hugo version

Expected output should include "extended":

hugo v0.139.4+extended linux/amd64

Install Dependencies#

From the docs/ directory:

npm install

Preview Documentation Locally#

Start the Hugo development server:

cd docs
hugo server

Open your browser to http://localhost:1313. The site auto-reloads when you save changes.

Useful flags:

  • hugo server -D - Include draft pages
  • hugo server --disableFastRender - Full rebuild on changes
  • hugo server --bind 0.0.0.0 - Allow external access

Documentation Structure#

Porch documentation is organized in numbered sections:

  • Overview - What Porch is, why it exists, and its role in the ecosystem
  • Concepts - Core concepts like Package, Repository, and Lifecycle
  • Installation - Installation, prerequisites, and first steps
  • Guides - Step-by-step task-oriented guides
  • Architecture - Internal architecture and component details
  • Configuration - Configuration options and deployment scenarios
  • CLI & API - CLI commands and API reference documentation
  • Troubleshooting - Common issues and solutions
  • Glossaru - Term definitions organized by topic
  • Contribution - How to contribute to Porch (this section)

Writing Guidelines#

File Naming#

  • Use lowercase with hyphens: package-lifecycle.md
  • Landing pages: _index.md
  • Descriptive names: installing-porch.md not install.md

Front Matter#

Every page needs front matter:

---
title: "Page Title"
type: docs
weight: 1
description: Brief description for SEO and navigation
---
  • weight: Controls ordering (lower numbers appear first)
  • description: Appears in navigation and search results

Markdown Style#

Headings: Use sentence case, not title case

## Package lifecycle stages

Code blocks: Always specify language

```bash
kubectl get packagerevisions
```

Internal links: Use Hugo relref shortcodes

See [Package Lifecycle]({{%/* relref "package-lifecycle" */%}}).

External links: Use standard markdown

[Kubernetes documentation](https://kubernetes.io/docs/)

Alerts (info/warning boxes): Use Docsy alert shortcodes

{{%/* alert title="Note" color="primary" */%}}
Important information here.
{{%/* /alert */%}}

Content Guidelines#

Be concise: Get to the point quickly

Use examples: Show, don't just tell

Verify accuracy: Test commands and examples; include expected command output if reasonably short

Consider audience: Assume Kubernetes familiarity; explain Porch-specific concepts

Avoid jargon: Define terms/expand acronyms on first use, or link to glossary

Making Changes#

Create a Branch#

git checkout -b docs-improve-package-lifecycle

Make Your Changes#

Edit files in docs/content/en/docs/

Preview Changes#

cd docs
hugo server

Verify your changes at http://localhost:1313

Commit Changes#

git add docs/content/en/docs/2_concepts/package-lifecycle.md
git commit -m "docs: clarify package lifecycle transitions"

Commit message format:

  • Start with docs: prefix
  • Use imperative mood ("add" not "added")
  • Keep first line under 72 characters

Push and Create PR#

git push origin -u docs-improve-package-lifecycle

Open a pull request on GitHub with:

  • Clear title describing the change
  • Description explaining what and why
  • Reference related issues if applicable

The EasyCLA bot will prompt you to sign the CLA if you haven't already (see contributing [Before You Start]({{% relref "../" %}})).

Special Documentation Tasks#

Generating API Reference#

See [API Reference Generation]({{% relref "api-ref-generation" %}}) for instructions on regenerating API documentation from Go source code.

Adding and editing Diagrams#

Diagrams are stored in docs/static/images/porch/ as .drawio.svg files. Diagrams created in this format can be opened in the draw.io editor, edited freely, and saved as-is. They can then be referenced in the Markdown files as normal SVG images.

Reference in markdown:

![Package Lifecycle](/images/porch/Porch-Architecture.drawio.svg)

Adding New Sections#

To add a new top-level section:

  1. Create directory: docs/content/en/docs/13_new_section/
  2. Add landing page: 13_new_section/_index.md
  3. Set appropriate weight in front matter
  4. Add content files as needed

Review Process#

Documentation PRs are reviewed by maintainers. Expect feedback on:

  • Technical accuracy
  • Clarity and readability
  • Consistency with existing docs
  • Proper formatting and links

Address feedback by pushing additional commits to your branch.

Getting Help#

If you have questions:

  • Comment on your PR
  • Open a GitHub discussion
    • Be sure to add the area/porch label when starting your discussion
  • Ask in the Nephio Slack #porch channel