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 – 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.

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
• 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
2. Click the “Fork” button in the top right
3. This creates your own copy of the repository

2. Clone Your Fork

git clone https://github.com/YOUR_USERNAME/docs.git
cd docs

3. Set Up Remote Tracking

# 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.

# 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.

# 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:

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!

# Boot a scoped Mintlify preview (~2 seconds vs ~10 minutes cold)
lpd dev --scoped --scope-tab <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

# 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:

git commit -m "Update .allowlist" --trailer "allowlist-edit=true"

If a human intentionally needs to allow file deletions, use:

git commit -m "Remove obsolete files" --trailer "allow-deletions=true"

9. Push to Your Fork

git push origin docs/your-branch-name

10. Create a Pull Request

1. Navigate to 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:

## 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 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

# 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

# Boot a scoped preview against the 1,128-page nav (~2 seconds)
lpd dev --scoped --scope-tab <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.

Project Structure

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.

Page templates (3)

File	Use it for	Matching snippet
snippets/templates/pages/faq-page.mdx	FAQ pages with a standard <AccordionGroup> 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.

Block templates (2)

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 <Card, so you can expand them after typing the angle bracket without generating <<.

File	Snippets	Scope
.vscode/mdx.code-snippets	17	Frontmatter, page scaffolds, and reusable MDX blocks
.vscode/mintlify.code-snippets	25	Mintlify built-in components
.vscode/components.code-snippets	115	Livepeer custom components

Frontmatter and metadata (7)

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.

---
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.

Page scaffolds (8)

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 <AccordionGroup>
troubleshootingPage	Troubleshooting page scaffold with Symptom, Cause, Fix, and Verify
openapiPage	OpenAPI endpoint scaffold with openapi: METHOD /path frontmatter and <OpenAPI />

All page scaffolds default to status: draft, include the fallback OG block, and omit lastVerified.

Block snippets (2)

Prefix	Inserts
relatedPages	## Related Pages plus a two-card <CardGroup> 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 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
• 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 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

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

Style Guide

Complete styling guidelines, Mintlify gotchas, and best practices.

Component Library

Reference all custom components with live examples and usage instructions.

Mintlify Documentation

Official Mintlify documentation for built-in components and features.

GitHub Repository

Source code and issue tracker for the documentation.

Documentation Guide

Learn how the documentation is structured and organised.

CODEOWNERS

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 for structure and conventions
• Review the Style Guide for styling guidelines
• Check the Component Library for component usage
• Review 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.