Skip to content

README 2.md

Latest commit

 

History

History
251 lines (173 loc) · 9.05 KB

README 2.md

File metadata and controls

251 lines (173 loc) · 9.05 KB

Livepeer Documentation Repository

This repository powers the Livepeer documentation experience and docs operations stack. It contains:

  • public docs content and navigation
  • component/data/snippet infrastructure
  • CLI, hooks, checks, and CI workflows
  • automation pipelines for content freshness
  • internal governance documentation

Live site: docs.livepeer.org

5-Minute Overview

If you only have a few minutes, this is the model:

  1. v2/pages/ + snippets/ are the primary docs content system.
  2. docs.json controls navigation/routes.
  3. lpd is the maintainer CLI for setup/dev/test/hooks/scripts.
  4. .githooks/, tests/, and CI workflows enforce quality gates.
  5. docs-guide/ is the internal source of truth for navigating all repo capabilities.

Quick Start

Prerequisites

  • Node.js 22+ for local checks/CI parity
  • Mintlify CLI for local docs runtime
npm i -g mintlify

Bootstrap + run

bash lpd setup --yes
lpd dev

For very large docs.json runs (multi-version/language) use scoped dev profile mode:

lpd dev --scoped --scope-version v2 --scope-language en --scope-tab Developers

Interactive scoped picker:

lpd dev --scoped --scope-interactive

If lpd is not on PATH yet:

bash lpd dev

Quick local validation

lpd test --staged
lpd test --staged --wcag
lpd test --staged --link-audit-external

Hot Reload Troubleshooting

If mint dev stops hot-reloading all pages, use this flow:

bash tools/scripts/dev/ensure-mint-watcher-patch.sh --check
bash tools/scripts/dev/ensure-mint-watcher-patch.sh --apply

Known trigger:

  • a repo path that includes [ / ] can break chokidar watch events if Mint watcher globbing is not disabled.

Recovery:

  1. Use lpd dev (or bash tools/scripts/mint-dev.sh) so the launcher applies the patch preflight and uses a watcher-safe path fallback.
  2. Re-run bash tools/scripts/dev/ensure-mint-watcher-patch.sh --apply after mint update.

For very large docs trees with sluggish route transitions:

  1. Run lpd dev --scoped ... to load only the active version/language/tab/prefix.
  2. Add --skip-external-fetch during local iterations when external snippets do not need refresh.

Core Capabilities (At a Glance)

Frontend Docs Platform

  • Mintlify-driven docs UI and routing
  • componentized page system via snippets/components/
  • structural/style enforcement through automated checks

Backend-Like Docs Operations Layer

  • unified CLI (lpd) for setup/dev/test/hooks/script execution
  • enforcement scripts for style, MDX, links/imports, navigation, and script docs
  • GitHub issue templates and PR templates for governance quality
  • pre-commit checks and CI checks including browser validations

AI / Automation / Pipelines

  • GitHub Actions + n8n assets for automated updates
  • showcase and trending/community content pipelines
  • automated maintenance scripts (indexing, SEO/AEO support, glossary support)

Product and Technical Documentation System

  • role-based IA across developers, gateways, orchestrators, delegators, resources
  • product-focused content layer plus deep technical guides
  • references, APIs, and integration data surfaces

Where Details Live (Canonical Internal Map)

docs-guide/ is the canonical internal navigation source of truth for repository features and functionality.

Need Canonical doc
Start here + update rules docs-guide/README.mdx
Source-of-truth boundaries docs-guide/source-of-truth-policy.mdx
Full feature inventory docs-guide/feature-guides/feature-map.mdx
System/data/control flow docs-guide/feature-guides/architecture-map.mdx
CLI commands and runbooks docs-guide/lpd.mdx
Validation + enforcement gates docs-guide/quality-testing/quality-gates.mdx
Automation pipelines map docs-guide/feature-guides/automation-pipelines.mdx
Content system and IA model docs-guide/feature-guides/content-system.mdx
APIs and data integrations docs-guide/feature-guides/data-integrations.mdx
Generated pages tree inventory docs-guide/indexes/pages-index.mdx
Generated components inventory docs-guide/indexes/components-index.mdx
Generated script inventory docs-guide/indexes/scripts-index.mdx
Generated workflow inventory docs-guide/indexes/workflows-index.mdx
Generated issue/PR template inventory docs-guide/indexes/templates-index.mdx

Contributing (Quick Path)

  1. Read style and component standards:
  2. Install/update hooks:
./.githooks/install.sh
  1. Create a branch, make changes, run lpd dev, commit, and open a PR.

Codex Branch Contract (codex/*)

For agent implementation branches, use:

  • branch name: codex/<issue-id>-<slug>
  • task contract file: .codex/task-contract.yaml
  • required PR sections: Scope, Validation, Follow-up Tasks
  • override policy (human-directed only): ai-tools/ai-rules/HUMAN-OVERRIDE-POLICY.md

Enforcement runs on codex/* only via:

  • .githooks/pre-push (contract + scope + non-fast-forward block by default)
  • tests/run-pr-checks.js (CI contract + PR body checks)

To auto-fill PR sections from task contract metadata:

node tools/scripts/create-codex-pr.js --create

This generates .codex/pr-body.generated.md and calls gh pr create --body-file .... Codex PR CI also requires the generated marker in the PR body, so manual bodies without the marker fail contract validation.

When a human explicitly requests merge or no-verify commit operations:

  • safe merge flow: node tools/scripts/codex-safe-merge-with-stash.js --target <branch-or-ref>
  • audited no-verify commit flow: node tools/scripts/codex-commit.js --message "..." --no-verify --human-override true --override-note "..."

Contributor deep docs:

Quality Gates Summary

Local (pre-commit)

  • .githooks/pre-commit runs structure/style verification and staged checks
  • includes script docs enforcement and pages index synchronization
  • includes staged WCAG accessibility audit with conservative autofix for common raw-tag issues
  • docs-guide source-of-truth checks currently run in advisory mode

CI (GitHub Actions)

  • changed-file quality suite: .github/workflows/test-suite.yml
  • v2 browser sweep: .github/workflows/test-v2-pages.yml
  • broken links check currently advisory while cleanup is ongoing

Deep matrix:

Repository Orientation

High-level directory map:

  • v2/pages/ active docs pages
  • v1/ legacy/frozen docs
  • snippets/ components, data, automations, shared assets
  • tools/scripts/ operational/generation scripts
  • tests/ unit/integration checks and runners
  • .githooks/ local hook scripts
  • .github/workflows/ CI and scheduled automations
  • api/ OpenAPI and related specs
  • docs-guide/ internal docs navigation source of truth

Automation Summary

Key automation categories:

  • content freshness (forum/blog/youtube/releases/showcase)
  • CI quality and browser validation
  • issue intake/labeling and review tooling
  • docs maintenance scripts and generated catalogs

Automation deep docs:

AI and Maintainer Guidance

  • AI assistant rules and safety: tools/ai-rules/
  • repository AI guidance files: .github/AGENTS.md, .cursorrules

Source-of-Truth Contract (Short Form)

  • Code/tests are source of truth for behavior.
  • docs-guide/ is source of truth for internal capability navigation.
  • README.md is high-level orientation and link hub.
  • Generated indexes must be regenerated, not hand-edited.

Regenerate docs-guide generated indexes:

node tools/scripts/generate-docs-guide-indexes.js --write
node tools/scripts/generate-docs-guide-pages-index.js --write
node tools/scripts/generate-docs-guide-components-index.js --write
node tests/unit/script-docs.test.js --write --rebuild-indexes