> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Contribute To The Docs
> Contribute to the Livepeer documentation and help us make it even better!
We love community feedback and contributions, and it's our mission to make it easy for everyone to contribute to these docs and provide feedback for us to make them even better!
**New contributor?** The fastest path is the [Docs Guide overview](/v2/resources/documentation-guide/index) – five steps from clone to first PR, plus the full IA tree and every feature mentioned. For the canonical, internal-maintainer flow with override trailers and governance approval labels, see [`docs-guide/contributing/contributing`](/v2/resources/documentation-guide/contributing/contributing).
## Provide Feedback
### On Any Page
You can provide feedback directly on any documentation page:
* **Thumbs Up/Down** - Quick feedback on whether the page was helpful
* **Comments** - Share specific feedback, suggestions, or questions
* **Issue Reporting** - Report errors, outdated information, or broken links
Feedback mechanisms are provided by Mintlify. Look for feedback options at the bottom of pages or in the page header.
### General Feedback Channels
If you prefer other channels:
* **GitHub Issues** - Open an issue in the [Livepeer Docs repository](https://github.com/livepeer/docs)
* **Discord** - Share feedback in the Livepeer community Discord
* **Email** - Contact the documentation team directly
## Contributing to the Docs
We welcome contributions from everyone, regardless of technical background!
### Non-Technical Contributions
You don't need to know Git or Markdown to contribute:
#### Option 1: Feedback Form
A feedback form is available for non-technical contributions. This allows you to suggest improvements, report issues, or share content ideas without needing to work with code.
#### Option 2: Content Suggestions
* Identify areas that need clarification
* Suggest new topics or guides
* Report outdated information
* Share use cases or examples
### Technical Contributions (Git & Markdown)
If you're comfortable with Git and Markdown, you can contribute directly:
## Pull Request Workflow
### Step-by-Step Guide
#### 1. Fork the Repository
1. Navigate to [github.com/Livepeer/docs](https://github.com/livepeer/docs)
2. Click the "Fork" button in the top right
3. This creates your own copy of the repository
#### 2. Clone Your Fork
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
git clone https://github.com/YOUR_USERNAME/docs.git
cd docs
```
#### 3. Set Up Remote Tracking
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Add the original repository as upstream
git remote add upstream https://github.com/livepeer/docs.git
# Verify remotes
git remote -v
```
#### 4. Create a Branch
**Important:** Always create a new branch for your changes. Never commit directly to `main` or `docs-v2`.
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Make sure you're on the latest version
git checkout docs-v2
git pull upstream docs-v2
# Create a new branch with a descriptive name
git checkout -b docs/fix-typo-quickstart-guide
# or
git checkout -b docs/add-api-example
# or
git checkout -b docs/update-component-docs
```
**Branch naming conventions:**
* `docs/` prefix for documentation changes
* Use descriptive names: `docs/fix-typo-quickstart-guide`
* Use kebab-case (lowercase with hyphens)
#### 5. Run setup
The repository ships a unified Bash CLI at `tools/lpd` that installs hooks, dependencies, and (optionally) puts itself on your `$PATH`. Use it instead of installing Mintlify or Node packages by hand.
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# One non-interactive command that installs git hooks, deps, and PATH integration
bash lpd setup --yes
# Confirm your environment is ready
lpd doctor
```
Pre-commit hooks automatically run staged validators for MDX render, redirect integrity, allowlist guards, and the no-deletion rule before you commit – in under 60 seconds. They are installed automatically by `lpd setup`.
The pre-commit hook validates:
* MDX render (catches broken JSX before commit)
* `docs.json` redirect integrity
* `.allowlist` and `v1/` protection
* Codex branch isolation (only for `codex/*` branches)
* Frontmatter completeness, voice (UK English, no em-dashes), style tokens, JSDoc headers
#### 6. Make Your Changes
Edit the relevant files:
**Where to edit content:**
* **Main documentation pages:** `v2/` (organised by section)
* **Components:** `snippets/components/`
* **Data files:** `snippets/data/`
* **Assets:** `snippets/assets/`
**File structure:**
```text icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
v2/
├── home/ # Home tab content
├── about/ # About tab content
├── community/ # Community tab content
├── developers/ # Developers tab content
├── gateways/ # Gateways tab content
├── orchestrators/ # Orchestrators tab content
├── lpt/ # LPT token and delegation content
├── solutions/ # Solutions and product content
├── resources/ # Resources tab content
└── internal/ # Internal documentation
```
**Naming conventions:**
* Use kebab-case for file names: `quickstart-guide.mdx`
* Use descriptive names that reflect content
* Follow the existing structure in each section
#### 7. Test Locally
**Always test your changes locally before submitting a PR!**
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Boot a scoped Mintlify preview (~2 seconds vs ~10 minutes cold)
lpd dev --scoped --scope-tab
# Or full unscoped dev server
lpd dev
```
This starts a local server (usually at `http://localhost:3000`) where you can preview your changes. `lpd dev --scoped` filters `docs.json` to the named tab so Mintlify cold-starts in seconds against the 1,128-page nav. Tab names fuzzy-match (`Orch`, `Resource`, `Gate`).
**What to check:**
* ✅ Pages render correctly
* ✅ No console errors
* ✅ Links work correctly
* ✅ Components display properly
* ✅ Both light and dark modes work
* ✅ Mobile responsiveness
#### 8. Commit Your Changes
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Stage your changes
git add .
# Commit with a clear message
git commit -m "docs: fix typo in quickstart guide"
```
**Commit message conventions:**
* Use prefixes: `docs:`, `fix:`, `feat:`, `chore:`
* Be descriptive: "docs: add API authentication example"
* Reference issues: "docs: update Gateway setup (fixes #123)"
**The pre-commit hook will run automatically** and may block your commit if there are style guide violations.
If a human intentionally needs to edit `.allowlist`, use:
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
git commit -m "Update .allowlist" --trailer "allowlist-edit=true"
```
If a human intentionally needs to allow file deletions, use:
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
git commit -m "Remove obsolete files" --trailer "allow-deletions=true"
```
#### 9. Push to Your Fork
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
git push origin docs/your-branch-name
```
#### 10. Create a Pull Request
1. Navigate to [github.com/Livepeer/docs](https://github.com/livepeer/docs)
2. You should see a banner suggesting to create a PR from your recent push
3. Click "Compare & pull request"
4. Fill out the PR template:
* **Title:** Clear, descriptive title
* **Description:** Explain what and why you changed
* **Related Issues:** Link to any related issues
* **Type:** Mark as documentation change
* **Testing:** Describe how you tested
**PR Template:**
```markdown icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
## Description
Brief description of changes
## Type of Change
- Bug fix (typo, broken link, incorrect information)
- New content (guide, tutorial, example)
- Content improvement (clarification, better examples)
- Component or styling update
## Related Issues
Fixes #123
## Testing
- Tested locally with `lpd dev --scoped`
- Checked light and dark modes
- Verified all links work
- No console errors
```
#### 11. Address Review Feedback
All PRs require at least one review from a maintainer. See [Review Process](#review-process) below for details.
* Respond to comments
* Make requested changes
* Push updates to the same branch (they'll appear in the PR automatically)
* Mark conversations as resolved when done
#### 12. Merge and Cleanup
Once your PR is approved and merged:
* Delete your branch locally: `git branch -d docs/your-branch-name`
* Delete your branch on GitHub (option available after merge)
* Update your fork: `git checkout docs-v2 && git pull upstream docs-v2`
## Development Setup
### Prerequisites
* **Node.js** (v18 or higher recommended)
* **Git**
* **GitHub account**
### Installation
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Clone the repository
git clone https://github.com/livepeer/docs.git
cd docs
# One non-interactive command installs hooks, deps, and PATH integration
bash lpd setup --yes
# Verify the environment is ready
lpd doctor
```
`lpd setup` installs the Mintlify CLI for you and registers the `.githooks/` pre-commit gates. You do not need to run `npm i -g mintlify` or `./.githooks/install.sh` separately.
### Running Locally
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Boot a scoped preview against the 1,128-page nav (~2 seconds)
lpd dev --scoped --scope-tab
# Or full unscoped dev server
lpd dev
# Server runs on http://localhost:3000 by default
```
For the full `lpd` reference – every subcommand, every flag, repair flows, the script catalogue – see [the canonical lpd CLI page](/v2/resources/documentation-guide/tooling/lpd-cli).
### Project Structure
```text icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
docs/
├── v2/ # Main documentation pages (MDX)
├── snippets/ # Reusable components and data
│ ├── components/ # React/JSX components
│ ├── data/ # Data files (JSX)
│ ├── assets/ # Images, logos, media
│ └── scripts/ # Automation scripts
├── .github/ # GitHub Actions workflows
├── .githooks/ # Pre-commit hooks
├── docs.json # Mintlify navigation config
└── style.css # Global CSS variables
```
## Authoring Helpers
Use the checked-in templates and workspace snippets before hand-authoring new page shells. They keep frontmatter, OG metadata, and common page layouts consistent across contributors.
### MDX Templates
Checked-in templates live under `snippets/templates/` so they stay versioned, reviewable, and available to every contributor.
| File | Use it for | Matching snippet |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------- |
| `snippets/templates/pages/faq-page.mdx` | FAQ pages with a standard `` structure | `faqPage` |
| `snippets/templates/pages/troubleshooting-page.mdx` | Operational and debugging pages with `Symptom`, `Cause`, `Fix`, and `Verify` sections | `troubleshootingPage` |
| `snippets/templates/pages/openapi-endpoint-page.mdx` | API endpoint pages that use `openapi: METHOD /path` frontmatter | `openapiPage` |
All three page templates default to `status: draft`, use `/snippets/assets/media/og-images/fallback.png`, and intentionally omit `lastVerified` until the page is current.
| File | Use it for | Matching snippet |
| ------------------------------------------------- | --------------------------------------------------------------- | ------------------ |
| `snippets/templates/blocks/related-pages-cta.mdx` | Related reading or next-step CTA blocks at the bottom of a page | `relatedPages` |
| `snippets/templates/blocks/comparison-matrix.mdx` | Product, workflow, or architecture comparison sections | `comparisonMatrix` |
The full template catalogue lives in `snippets/templates/README.mdx`.
### VS Code Snippets
Workspace snippets in `.vscode/` load automatically when you open this repo in VS Code.
JSX tag snippets accept both bare component names such as `Card` and opening-tag prefixes such as `
Source: `.vscode/mdx.code-snippets`
Use `frontmatter` for the full draft block, `fm` for the smaller version, and the single-field snippets when you need to patch one field in place.
```yaml icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
---
title: "Page Title"
sidebarTitle: Page Title
description: "Describe the page."
audience: developer
pageType: reference
purpose: reference
status: draft
keywords:
- livepeer
- keyword
'og:image': /snippets/assets/media/og-images/fallback.png
'og:image:alt': Livepeer Docs social preview image
'og:image:type': image/png
'og:image:width': 1200
'og:image:height': 630
---
```
`lastVerified` is now a separate opt-in snippet. Add it only when the page status is `current`, `published`, `production`, or `verified_2026`.
| Prefix | Layout |
| --------------------- | ------------------------------------------------------------------------------------ |
| `lp-overview` | Overview page with `Overview`, `Key Concepts`, and next-step cards |
| `lp-howto` | How-to page with `Prerequisites`, `Steps`, and `Verify` |
| `lp-tutorial` | Tutorial page with `Prerequisites`, guided `Steps`, and `Next Steps` |
| `lp-reference` | Reference page with sections for inputs, behaviour, and examples |
| `lp-landing-frame` | Frame-mode landing scaffold using the existing portal components |
| `faqPage` | FAQ page scaffold with `` |
| `troubleshootingPage` | Troubleshooting page scaffold with `Symptom`, `Cause`, `Fix`, and `Verify` |
| `openapiPage` | OpenAPI endpoint scaffold with `openapi: METHOD /path` frontmatter and `` |
All page scaffolds default to `status: draft`, include the fallback OG block, and omit `lastVerified`.
| Prefix | Inserts |
| ------------------ | ------------------------------------------------------------------ |
| `relatedPages` | `## Related Pages` plus a two-card `` CTA block |
| `comparisonMatrix` | `## Compare Options` plus a decision table and recommendation note |
Use these when the surrounding page already exists and you only need a standard decision or navigation block.
## Contribution Guidelines
### Style Guide
**MANDATORY:** Read the [Style Guide](/v2/resources/documentation-guide/copy-style/style-guide) before making any changes!
**Critical rules:**
* ✅ Use CSS Custom Properties (`var(--accent)`) only
* ❌ Never use legacy theme helpers or hardcode colours
* ✅ Use absolute imports: `/snippets/components/...`
* ❌ No relative imports for snippets
* ✅ Test in both light and dark modes
### Component Usage
* Use components from the [Component Library](/v2/resources/documentation-guide/component-library/overview)
* Check component documentation before creating new components
* Follow existing patterns and conventions
### Content Guidelines
* **Be clear and concise** - Write for your audience
* **Use examples** - Show, don't just tell
* **Keep it up-to-date** - Remove outdated information
* **Link appropriately** - Use internal links to related content
* **Add keywords** - Help with discoverability
### Code Examples
* Use proper syntax highlighting
* Include complete, runnable examples when possible
* Explain what the code does
* Show expected output when relevant
### Testing Requirements
Before submitting a PR, ensure:
* All pages render without errors
* No console errors in browser
* Links work correctly
* Components display properly
* Works in both light and dark modes
* Mobile responsive
* Pre-commit hooks pass
## Review Process
### Who Reviews What
Documentation changes are reviewed by section owners. See [CODEOWNERS](https://github.com/livepeer/docs/blob/docs-v2/.github/CODEOWNERS) for details.
**General review assignments:**
* **Developers section:** Developer relations team
* **Gateways section:** Gateway team
* **Orchestrators section:** Orchestrator team
* **Delegators section:** Delegator team
* **Resources section:** Documentation team
* **General/Cross-cutting:** Documentation team
### Review Timeline
We aim to review PRs within **48-72 hours** during business days.
* **Small changes** (typos, broken links): Usually reviewed within 24 hours
* **Medium changes** (content updates, examples): 48-72 hours
* **Large changes** (new guides, major restructuring): May take longer, discuss in issue first
### Review Criteria
Reviewers check for:
* ✅ Accuracy and correctness
* ✅ Style guide compliance
* ✅ Proper component usage
* ✅ Working links and examples
* ✅ Appropriate tone and clarity
* ✅ SEO and discoverability
### Addressing Feedback
* Respond to all comments
* Make requested changes or explain why not
* Push updates to the same branch
* Mark conversations as resolved
* Request re-review when ready
## What to Contribute
We welcome contributions in many areas:
### Content Improvements
* Fix typos and grammatical errors
* Clarify confusing explanations
* Update outdated information
* Improve code examples
* Add missing information
### New Content
* Tutorials and guides
* Quickstarts for new features
* API documentation
* Code examples and snippets
* Component examples
### Technical Improvements
* Component enhancements
* Styling improvements
* Automation scripts
* Documentation tooling
### Translations
* Help translate content (when multilingual support is ready)
* Improve existing translations
## File Structure Guide
### Where to Edit Different Types of Content
| Content Type | Location | Example |
| -------------- | ---------------------- | ---------------------------------------------- |
| **Main pages** | `v2/[section]/` | `v2/developers/guides-and-tools/` |
| **Components** | `snippets/components/` | `snippets/components/elements/links/Links.jsx` |
| **Data files** | `snippets/data/` | `snippets/data/gateways/flags.jsx` |
| **Assets** | `snippets/assets/` | `snippets/assets/logos/` |
| **Navigation** | `docs.json` | Root level |
| **Styling** | `style.css` | Root level |
### Section Organisation
```text icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
v2/
├── home/ # Home tab
│ ├── mission-control.mdx
│ ├── introduction/
│ └── project-showcase/
├── about/ # About tab
│ ├── about-portal.mdx
│ └── core-concepts/
├── developers/ # Developers tab
│ ├── building-on-livepeer/
│ ├── guides-and-tools/
│ └── builder-opportunities/
├── gateways/ # Gateways tab
│ ├── gateway-portal.mdx
│ ├── run/
│ └── build/
├── orchestrators/ # Orchestrators tab
│ ├── orchestrator-portal.mdx
│ └── run/
├── delegators/ # Delegators tab
│ └── delegator-portal.mdx
└── resources/ # Resources tab
├── portal.mdx
└── documentation-guide/
```
## Resources for Contributors
Complete styling guidelines, Mintlify gotchas, and best practices.
Reference all custom components with live examples and usage instructions.
Official Mintlify documentation for built-in components and features.
Source code and issue tracker for the documentation.
Learn how the documentation is structured and organised.
See who reviews changes to each section.
## Contribution Workflow Summary
### For Small Changes (Typos, Broken Links)
1. Fork and create branch
2. Make the fix
3. Test locally
4. Submit PR
5. Address any feedback
### For Medium Changes (Content Updates, Examples)
1. Open an issue to discuss (optional but recommended)
2. Fork and create branch
3. Make changes
4. Test thoroughly
5. Submit PR with clear description
6. Iterate based on feedback
### For Large Changes (New Guides, Major Restructuring)
1. **Always discuss first** - Open an issue or discussion
2. Get feedback and approval before starting
3. Create a detailed plan
4. Fork and create branch
5. Work incrementally (consider draft PR)
6. Submit PR with comprehensive description
7. Iterate based on extensive feedback
## Recognition
Contributors are recognised and appreciated! Your contributions help make the Livepeer documentation better for everyone in the community.
## Questions?
If you have questions about contributing:
* Check the [Documentation Guide](/v2/resources/documentation-guide/documentation-guide) for structure and conventions
* Review the [Style Guide](/v2/resources/documentation-guide/copy-style/style-guide) for styling guidelines
* Check the [Component Library](/v2/resources/documentation-guide/component-library/overview) for component usage
* Review [CODEOWNERS](https://github.com/livepeer/docs/blob/docs-v2/.github/CODEOWNERS) to see who reviews what
* Open a GitHub issue or discussion
* Ask in the Livepeer Discord community
Thank you for helping improve the Livepeer documentation.