Contributing to the Livepeer Docs

This is the canonical contributor entrypoint for this repository. For hook details, see Git Hooks.

1) Start Here

# 1) Bootstrap tools/tests/hooks
bash lpd setup --yes

# 2) Run docs locally
lpd dev

# 3) Run staged checks before opening a PR
lpd test --staged

If lpd is not on your PATH yet, use bash lpd <command>.

2) What You Can Contribute

Docs Content

Update guides, references, quickstarts, and troubleshooting pages in v2/.

Component Library

Improve reusable components and examples under snippets/components/.

Tooling & Scripts

Improve lpd, local checks, generators, and operational scripts.

CI & Automation

Improve issue/PR intake, workflows, and content freshness automation.

3) Repo Map for Contributors

4) Issue Templates (What to File, When)

5) PR Workflow

Step 1: Branch and scope

Fork or branch from the active docs branch, keep PRs focused, and avoid mixing unrelated changes.

Step 2: Implement and verify locally

Make changes, run lpd dev to preview, then run lpd test --staged.

Step 3: Open PR with the correct template

PR templates in this repo:

.github/pull-request-template-v2.md
.github/pull_request_template.md

Fill in scope, testing evidence, and linked issues.

Step 4: Address review feedback

Push fixes to the same branch, re-run staged checks, and resolve reviewer comments.

Step 5: Merge readiness

Ensure required blocking checks pass. Advisory workflows can still surface follow-up work.

5a) Codex Branch Contract (`codex/*`)

For implementation tasks run by agents, use:

branch format: codex/<issue-id>-<slug>
task contract: .codex/task-contract.yaml
PR required sections: Scope, Validation, Follow-up Tasks

These checks are enforced only on codex/* branches by local hooks and PR CI.

Task Contract Example

task_id: 1234
base_branch: docs-v2
branch: codex/1234-community-fix
scope_in:
  - v2/community/
  - docs.json
scope_out:
  - v1/
allowed_generated:
  - docs-index.json
acceptance_checks:
  - node operations/tests/run-pr-checks.js --base-ref docs-v2
risk_flags:
  - navigation
follow_up_issues:
  - 1250

Open a prefilled PR directly from contract metadata:

node operations/scripts/dispatch/ai/codex/create-codex-pr.js --create

6) Required Quality Gates

7) `lpd` CLI Contributor Commands

8) Component Library and Authoring Rules

Follow these rules strictly:

Use CSS custom properties (for example var(--accent)), not legacy JS theme objects.
Do not hardcode theme colors when a CSS variable should be used.
Use absolute snippet imports (/snippets/...), not relative snippet paths.
Do not import Mintlify global components or React hooks unnecessarily.

See canonical docs:

9) Scripts and Generated Indexes

node operations/scripts/generators/governance/catalogs/generate-docs-guide-indexes.js --write
node operations/scripts/generators/governance/catalogs/generate-docs-guide-pages-index.js --write
node operations/scripts/generators/governance/catalogs/generate-docs-guide-components-index.js --write
node operations/tests/unit/script-docs.test.js --write --rebuild-indexes

Generated indexes are read-only outputs. Regenerate them instead of hand-editing.

10) Human-Only Overrides and Safety

Do not use --no-verify in normal contribution flow.Human-only overrides:

.allowlist edits: --trailer "allowlist-edit=true"
file deletions outside allowed scope: --trailer "allow-deletions=true"

Canonical governance details:

root allowlist policy: docs-guide/policies/root-allowlist-governance.mdx
agent governance policy: docs-guide/policies/agent-governance-framework.mdx

11) Pre-PR Checklist

Changes are scoped and clearly described.
lpd dev preview looks correct for affected pages/components.
lpd test --staged passes.
Related links and references were verified.
PR template is fully completed with testing notes.
Any generated indexes affected by this change were regenerated.

12) Where to Ask for Help

GitHub Issues

Report bugs, page issues, feature/content requests, and tooling problems.

GitHub Discussions

Ask broader questions and start proposal threads.

Livepeer Discord

Get real-time community support.

Security Advisories

Report security issues privately.

Canonical References

Optional Visual-Explainer Workflows (Pilot)

This workflow is optional and maintainer-focused during the pilot period. It is not a required contributor quality gate and is not part of CI.

Use visual-explainer when you need high-signal review artifacts for structural changes or stakeholder-facing verification outputs.

Recommended Pilot Uses

/diff-review for structural PRs that touch docs.json, snippets/components/**, or .github/workflows/**
/plan-review for one-time gap analysis against the AI-first docs plan
/fact-check for delivery/retrospective claim verification
/project-recap for maintainer onboarding and handoff context

Artifact Naming Convention

YYYY-MM-DD_diff-review_<ref>.html
YYYY-MM-DD_plan-review_ai-first-plan.html

Scope and Boundaries

Keep generated artifacts out of this repository during the pilot.
Do not treat visual-explainer commands as Mintlify or GitHub Actions commands.
Keep persona-routing matrix output internal first; defer homepage/Mission Control placement until pilot validation is complete.

For full details and corrected repo path references, see:

docs-guide/features/visual-explainer-workflows.mdx

Technical References

Compendium

Knowledge Hub

Changelogs

Documentation Guide

Contributing to the Livepeer Docs

1) Start Here

2) What You Can Contribute

Docs Content

Component Library

Tooling & Scripts

CI & Automation

3) Repo Map for Contributors

4) Issue Templates (What to File, When)

5) PR Workflow

5a) Codex Branch Contract (`codex/*`)

6) Required Quality Gates

7) `lpd` CLI Contributor Commands

8) Component Library and Authoring Rules

9) Scripts and Generated Indexes

10) Human-Only Overrides and Safety

11) Pre-PR Checklist

12) Where to Ask for Help

GitHub Issues

GitHub Discussions

Livepeer Discord

Security Advisories

Canonical References

Optional Visual-Explainer Workflows (Pilot)

Recommended Pilot Uses

Artifact Naming Convention

Scope and Boundaries

​1) Start Here

​2) What You Can Contribute

Docs Content

Component Library

Tooling & Scripts

CI & Automation

​3) Repo Map for Contributors

​4) Issue Templates (What to File, When)

​5) PR Workflow

​5a) Codex Branch Contract (codex/*)

​6) Required Quality Gates

​7) lpd CLI Contributor Commands

​8) Component Library and Authoring Rules

​9) Scripts and Generated Indexes

​10) Human-Only Overrides and Safety

​11) Pre-PR Checklist

​12) Where to Ask for Help

GitHub Issues

GitHub Discussions

Livepeer Discord

Security Advisories

​Canonical References

​Optional Visual-Explainer Workflows (Pilot)

​Recommended Pilot Uses

​Artifact Naming Convention

​Scope and Boundaries

1) Start Here

2) What You Can Contribute

3) Repo Map for Contributors

4) Issue Templates (What to File, When)

5) PR Workflow

5a) Codex Branch Contract (`codex/*`)

6) Required Quality Gates

7) `lpd` CLI Contributor Commands

8) Component Library and Authoring Rules

9) Scripts and Generated Indexes

10) Human-Only Overrides and Safety

11) Pre-PR Checklist

12) Where to Ask for Help

Canonical References

Optional Visual-Explainer Workflows (Pilot)

Recommended Pilot Uses

Artifact Naming Convention

Scope and Boundaries