Contributing to Livepeer Docs: Onboarding Guide

[DeveloperAlly]

Contributing to Livepeer Docs

Welcome! Livepeer docs are open source and we value contributions from the community. This issue serves as a one-stop onboarding guide and a tracker for good first issues.

---

Quick start

# 1. Fork and clone
git clone https://github.com/<your-username>/docs.git && cd docs
git remote add upstream https://github.com/livepeer/docs.git

# 2. Check out the working branch
git checkout docs-v2

# 3. Set up the dev environment
bash tools/lpd setup --yes

# 4. Create your branch
git checkout -b docs/your-change-description

# 5. Start the local dev server
lpd dev

Note: The repo deploys from docs-v2, not main. Always branch from docs-v2.

---

Repo structure at a glance

Directory	What lives here
v2/	All current published docs pages (MDX)
v1/	Frozen legacy pages — do not edit
snippets/components/	Reusable JSX components
snippets/data/	Data files consumed by pages
snippets/assets/	Images, videos, logos
snippets/templates/	Page templates and examples
operations/	Scripts, tests, governance tooling
docs-guide/	Internal style guides and governance
docs.json	Navigation config (source of truth for routing)
.mintignore	Files excluded from the published site

Navigation (docs.json)

Pages are organised as: Version > Language > Tab (dropdown) > Anchor (section) > Group > Pages

Current v2 tabs: Home, About, Developers, Gateways, Orchestrators, Delegators, Solutions, Resources.

To add a page to the nav, add its path to the appropriate group in docs.json.

---

Writing conventions

File format

• All docs pages are MDX (.mdx extension, not .md)
• Frontmatter is required: title, description, sidebarTitle at minimum

Language and style

• UK English throughout (-ise, -our, -re)
• No em dashes. Use commas, colons, or semicolons instead
• No questions in headings
• Lead with facts, end with facts
• See the style guide for full rules

Mintlify constraints

• No import React from 'react' or React hooks in MDX pages
• Use root-absolute paths for imports (e.g. /snippets/components/...)
• Include file extensions in import paths
• No hardcoded colour values. Use CSS custom properties from style.css

Components

• 115+ custom components available in snippets/components/
• Browse templates in snippets/templates/ for page patterns
• VS Code snippets available. Run lpd vscode:install for autocomplete

---

Submitting a PR

Before you submit

• Pages render locally with lpd dev (no console errors)
• All links work (internal and external)
• Components display correctly
• Light and dark mode both look right
• Mobile responsive

Commit message format

Use conventional prefixes:

• docs: for content changes
• fix: for corrections
• feat: for new pages or features
• chore: for tooling, config, non-content

Branch naming

Use docs/ prefix with kebab-case: docs/fix-gateway-install-steps

PR template

The repo has a PR template with a checklist. Fill it in. Reviewers use it to assess your change.

Review process

• Reviews within 24 to 72 hours depending on scope
• Section owners (see CODEOWNERS) review area-specific changes
• Copy governance checks run automatically on PR

---

Good first issues

Looking to get started? Here are areas where contributions are especially welcome:

Content fixes

• Fix broken internal links (97 currently flagged across the site)
• Fix em-dashes in orchestrator FAQ and community guides (4 remaining)
• Add missing description frontmatter to pages that lack it

Typos and grammar

• Spot-check any v2/ page and submit fixes for typos, grammar, or unclear wording

Accessibility

• Add missing alt text to images
• Check heading hierarchy (h1, h2, h3 with no skipped levels)

Translation

• Help translate pages. See operations/scripts/integrators/content/language-translation/ for the i18n pipeline

Component examples

• Add usage examples for components in snippets/components/ that lack them

---

Resources

Resource	Link
Full contributing guide	contribute-to-the-docs
Style guide	style-guide
Live docs	docs.livepeer.org
Discord	Livepeer Discord

---

Questions?

Drop a comment on this issue or ask in the Livepeer Discord. We are happy to help you get started.