Contribute To The Docs

​

Provide Feedback

​

On Any 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

​

General Feedback 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

​

Non-Technical Contributions

​

Option 1: Feedback Form

​

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)

​

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

# Make sure you're on the latest version
git checkout docs-v2-preview
git pull upstream docs-v2-preview

# 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

• docs/ prefix for documentation changes
• Use descriptive names: docs/fix-typo-quickstart-guide
• Use kebab-case (lowercase with hyphens)

​

5. Install Pre-commit Hooks

# Install the pre-commit hook
./.githooks/install.sh

• Check for deprecated ThemeData usage
• Warn about hardcoded hex colors
• Validate MDX, JSON, and JavaScript syntax
• Check for relative imports
• Verify absolute import paths

​

6. Make Your Changes

• Main documentation pages: v2/pages/ (organized by section)
• Components: snippets/components/
• Data files: snippets/data/
• Assets: snippets/assets/

v2/pages/
├── 00_home/          # Home tab content
├── 01_about/         # About tab content
├── 02_community/     # Community tab content
├── 03_developers/    # Developers tab content
├── 04_gateways/      # Gateways tab content
├── 05_orchestrators/ # Orchestrators tab content
├── 06_delegators/    # Delegators tab content
├── 07_resources/     # Resources tab content
└── 09_internal/      # Internal documentation

• 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

# Install Mintlify CLI (if not already installed)
npm i -g mintlify

# Run the development server
mint dev

• ✅ 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"

• Use prefixes: docs:, fix:, feat:, chore:
• Be descriptive: “docs: add API authentication example”
• Reference issues: “docs: update gateway setup (fixes #123)”

​

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

## 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 `mint dev`
- [ ] Checked light and dark modes
- [ ] Verified all links work
- [ ] No console errors

​

11. Address Review Feedback

• 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

• 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-preview && git pull upstream docs-v2-preview

​

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

# Install Mintlify CLI globally
npm i -g mintlify

# Install pre-commit hooks
./.githooks/install.sh

​

Running Locally

# Start development server
mint dev

# Server runs on http://localhost:3000 by default

​

Project Structure

docs/
├── v2/pages/              # 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

​

Contribution Guidelines

​

Style Guide

• ✅ Use CSS Custom Properties (var(--accent)) only
• ❌ Never use ThemeData or hardcode colors
• ✅ 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

• 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

• 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

• 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

• ✅ 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

​

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

​

Section Organization

v2/pages/
├── 00_home/              # Home tab
│   ├── mission-control.mdx
│   ├── introduction/
│   └── project-showcase/
├── 01_about/             # About tab
│   ├── about-portal.mdx
│   └── core-concepts/
├── 03_developers/        # Developers tab
│   ├── building-on-livepeer/
│   ├── guides-and-resources/
│   └── builder-opportunities/
├── 04_gateways/          # Gateways tab
│   ├── gateway-portal.mdx
│   ├── run/
│   └── build/
├── 05_orchestrators/     # Orchestrators tab
│   ├── orchestrator-portal.mdx
│   └── run/
├── 06_delegators/        # Delegators tab
│   └── delegator-portal.mdx
└── 07_resources/         # Resources tab
    ├── resources-portal.mdx
    └── documentation-guide/

​

Resources for Contributors

​

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

​

Questions?

• 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

​

Non-Technical Contribution Proposal

​

Current Options

1. GitHub Web Editor — Edit files directly in the browser
2. Feedback Forms — Submit suggestions via forms
3. Issue Reporting — Open GitHub issues with content suggestions

​

Proposed Workflows

​

Option 1: Mintlify Web Editor Integration

1. Click “Edit this page” button on any documentation page
2. Opens Mintlify web editor (requires authentication)
3. Make edits in visual or markdown mode
4. Submit changes which create a GitHub PR automatically

• Mintlify web editor access
• GitHub authentication
• Automatic PR creation

​

Option 2: Form-Based Submission System

1. User fills out form with:
   • Page URL or section
   • Type of change (typo, clarification, new content)
   • Current text (if applicable)
   • Proposed text
   • Reason for change
2. Form submission creates GitHub issue
3. Maintainer reviews and either:
   • Implements the change
   • Converts to PR template for user
   • Requests more information

• Form creation (Google Forms, Typeform, or custom)
• GitHub API integration
• Issue template automation

​

Option 3: “Edit This Page” Button with PR Template

1. Click “Edit this page” button
2. Opens GitHub web editor for that file
3. User makes changes
4. GitHub prompts to create PR with template
5. User fills out PR description
6. PR is created for review

• Add “Edit this page” buttons to all pages
• Create PR template
• Link to GitHub web editor with correct branch

​

Option 4: External CMS Integration

1. Non-technical users edit content in CMS
2. CMS webhooks trigger GitHub Actions
3. Changes are automatically committed and PR created
4. Maintainer reviews PR

• CMS setup and configuration
• GitHub Actions workflow
• Content synchronization
• Authentication and permissions

​

Recommended Implementation Order

1. Phase 1 (Quick Win): Add “Edit this page” buttons linking to GitHub web editor
2. Phase 2 (Medium Effort): Create form-based submission system with GitHub issue automation
3. Phase 3 (Long-term): Evaluate Mintlify web editor integration or CMS solution

​

Feedback Welcome

• Open a GitHub issue with your suggestion
• Discuss in the Livepeer Discord
• Contact the documentation team