Contributing to Livepeer Docs: Onboarding Guide

Nobody has claimed this yet.

# 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

```bash
# 1. Fork and clone
git clone https://github.com//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](https://docs.livepeer.org/v2/resources/documentation-guide/copy-style/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](https://docs.livepeer.org/v2/resources/documentation-guide/contributing/contribute-to-the-docs) |
| Style guide | [style-guide](https://docs.livepeer.org/v2/resources/documentation-guide/copy-style/style-guide) |
| Live docs | [docs.livepeer.org](https://docs.livepeer.org) |
| Discord | [Livepeer Discord](https://discord.gg/livepeer) |

---

## Questions?

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

This is an onboarding tracker rather than a scoped change. Start with the listed entry points—v2/, docs.json, operations/scripts/integrators/content/language-translation/, and tools/lpd setup --yes—then choose a specific good-first task; done means a focused PR that satisfies its own validation checklist.

Written by the indexing model from the issue text.