Overview

Relevant source files

• .github/workflows/README.md
• .github/workflows/lint.yaml
• .github/workflows/preview.yaml
• README.md
• next.config.mjs
• package.json
• scripts/check-links.mjs
• yarn.lock

This repository implements the documentation infrastructure for Celestia at https://docs.celestia.org. It is a Next.js 16 static site using the Nextra documentation framework, with a critical multi-network version management system that synchronizes version data across Mainnet Beta, Mocha testnet, and Arabica devnet.

The system is characterized by:

• Static site generation via Next.js with output: 'export' configuration
• Multi-network version injection through remark-replace-variables plugin processing constants/*.json files
• Automated CI/CD with GitHub Actions for production (deploy.yml) and PR previews (preview.yaml)
• Quality assurance through check-links.mjs script and ESLint validation

Sources: README.md1-130 package.json1-55 next.config.mjs1-41

System Architecture

High-Level Component Diagram

The system processes MDX content through a build pipeline that injects network-specific versions, generates static output, and validates link integrity.

Sources: next.config.mjs1-41 package.json1-55 .github/workflows/deploy.yml .github/workflows/preview.yaml .github/workflows/lint.yaml

Multi-Network Version Management

The version management system is the most critical component (highest cluster importance in the codebase analysis). It maintains three separate version files that are injected into documentation during the build process.

Template syntax in MDX files:

• {{mainnetVersions['app-latest-tag']}} - Mainnet Beta versions
• {{mochaVersions['node-latest-tag']}} - Mocha testnet versions
• {{arabicaVersions['app-latest-tag']}} - Arabica devnet versions

Sources: README.md47-52 scripts/check-links.mjs159-176 next.config.mjs4-11

Technology Stack

Category	Technology	Version	Implementation
Framework	Next.js	16.0.8	package.json24
Documentation	Nextra	4.6.0	package.json25
UI	React	19.2.0	package.json27
Styling	Tailwind CSS	4.1.17	package.json50
Content	MDX	3.1.1	@mdx-js/mdx in yarn.lock
Math	rehype-katex	7.0.1	package.json32
Search	Pagefind	1.4.0	package.json45
Package Manager	Yarn	v1 lockfile	yarn.lock1-2
Linting	ESLint	9.39.1	package.json42
Git Hooks	simple-git-hooks	2.13.1	package.json49
Processing	unified	11.0.5	package.json52

Sources: package.json1-55 yarn.lock1-100

Directory Structure

celestiaorg/docs/
├── app/
│   ├── learn/           # Conceptual documentation
│   ├── build/           # Developer guides, APIs
│   ├── operate/         # Node operation guides
│   ├── layout.tsx       # Root layout component
│   └── **/_meta.js      # Navigation configuration
├── constants/
│   ├── mainnet_versions.json
│   ├── mocha_versions.json
│   ├── arabica_versions.json
│   └── general.json
├── plugins/
│   └── remark-replace-variables.mjs
├── scripts/
│   ├── check-links.mjs
│   └── generate-llms.js
├── public/
│   ├── img/             # Static images
│   └── llms.txt         # Generated LLM index
├── .github/workflows/
│   ├── deploy.yml       # Production deployment
│   ├── preview.yaml     # PR preview deployment
│   ├── lint.yaml        # Quality checks
│   └── latest-tags.yaml # Version updates
├── next.config.mjs      # Next.js configuration
├── package.json         # Dependencies and scripts
└── out/                 # Generated static site
    └── _pagefind/       # Search index

Content organization follows the user journey:

• app/learn/: Understanding Celestia (page.mdx files)
• app/build/: Integration guides (page.mdx files)
• app/operate/: Infrastructure operations (page.mdx files)

Sources: README.md117-122 README.md47-52

Build Process

Build Pipeline Execution

Configuration Details

Setting	Value	Location
Static export	output: 'export'	next.config.mjs25
Base path	process.env.BASE	next.config.mjs17-18
Asset prefix	process.env.BASE	next.config.mjs24
Trailing slash	true	next.config.mjs26
Image optimization	unoptimized: true	next.config.mjs28
Webpack mode	--webpack flag	package.json8
Remark plugins	[remarkReplaceVariables, remarkMath]	next.config.mjs11
Rehype plugins	[rehypeKatex]	next.config.mjs12

The --webpack flag is required because the experimental mdxRs feature does not support custom remark plugins like remarkReplaceVariables.

Sources: next.config.mjs1-41 package.json6-14 README.md27-34

Deployment Workflows

Workflow Overview

Workflow	Trigger	Destination	URL Pattern
deploy.yml	Push to main, manual	gh-pages branch	docs.celestia.org
preview.yaml	PR open/sync	celestiaorg/docs-preview	celestiaorg.github.io/docs-preview/pr-N/
preview.yaml	PR closed	Remove from docs-preview	N/A
lint.yaml	Push, PR, weekly	N/A (CI checks)	N/A

Production Deployment (deploy.yml)

Sources: .github/workflows/deploy.yml .github/workflows/README.md5-9

PR Preview Deployment (preview.yaml)

The preview system requires PR_PREVIEW_DEPLOY secret for write access to celestiaorg/docs-preview.

Sources: .github/workflows/preview.yaml1-144 .github/workflows/README.md11-16

Quality Assurance

Link Validation (check-links.mjs)

The scripts/check-links.mjs script validates internal and external links with variable resolution.

Key Functions:

• buildRouteInventory() scripts/check-links.mjs63-90 - Scans app/ for page.mdx files
• checkInternalLink() scripts/check-links.mjs108-156 - Validates against route inventory
• checkExternalLink() scripts/check-links.mjs352-494 - HTTP validation with retry
• replaceVariablesInUrl() scripts/check-links.mjs182-211 - Resolves {{mainnetVersions['key']}}
• processLinksConcurrently() scripts/check-links.mjs499-529 - Concurrent external checks

CLI Flags:

• --internal - Check internal links only
• --external - Check external links only
• --all - Check both (used in CI)
• --concurrency=N - Parallel external checks (default: 5, CI: 2)
• --skip=pattern1,pattern2 - Skip patterns

Sources: scripts/check-links.mjs1-812 README.md54-58

CI Validation (lint.yaml)

Git Hooks:

• Pre-push: npm run lint (package.json16-18)
• Managed by: simple-git-hooks (package.json49)
• Hook setup: npm run prepare (package.json12)

Sources: .github/workflows/lint.yaml1-53 package.json11-18

Development Commands

Command	Script	Purpose
yarn dev	next dev --webpack	Development server on http://localhost:3000
yarn build	next build --webpack	Production build → out/
yarn start	serve out	Preview static build locally
yarn lint	eslint	ESLint code quality checks
yarn check-links	node scripts/check-links.mjs	Link validation (add flags as needed)
yarn generate:llms	node scripts/generate-llms.js	Generate public/llms.txt
yarn prepare	simple-git-hooks	Install git hooks

Sources: package.json6-14 README.md16-25

Development Setup

Building Locally

Base Path Configuration

For subdirectory deployments (e.g., GitHub Pages previews):

• BASE - Asset prefix with trailing slash next.config.mjs17-18
• NEXT_PUBLIC_BASE_PATH - Client-side routing without trailing slash

Sources: README.md16-45 next.config.mjs16-24

Content System

Version Constants

Version data is stored in constants/ and injected via remarkReplaceVariables:

File	Network	Purpose
mainnet_versions.json	Mainnet Beta	Production version tags
mocha_versions.json	Mocha testnet	Testnet version tags
arabica_versions.json	Arabica devnet	Development version tags
general.json	All networks	Network-agnostic constants

Template Syntax in MDX:

Variable Resolution:

• Plugin: plugins/remark-replace-variables.mjs next.config.mjs4-11
• Loader: scripts/check-links.mjs:159-176]() loads constants for link validation
• Supported formats: {{var}} and {var} syntax

Sources: README.md47-52 scripts/check-links.mjs159-211 next.config.mjs4-11

Navigation (_meta.js)

Sidebar configuration per directory:

The _meta.js files define:

• Page order in sidebar
• Display titles
• External links (via href property)

Sources: README.md47-52 scripts/check-links.mjs323-347

Configuration Reference

Environment Variables

Variable	Format	Purpose	Example
BASE	/path/ (with trailing slash)	Asset prefix	/docs-preview/pr-123/
NEXT_PUBLIC_BASE_PATH	/path (no trailing slash)	Client-side routing	/docs-preview/pr-123

Implementation:

Sources: next.config.mjs16-24 README.md36-45 .github/workflows/preview.yaml39-41

Build Configuration

Setting	Value	Purpose
output	'export'	Enable static site generation
trailingSlash	true	Ensure /page/ URLs
images.unoptimized	true	Disable image optimization for static export
experimental.mdxRs	undefined	Disabled (custom remark plugins unsupported)

Sources: next.config.mjs25-32

System Integration Points

The documentation system integrates with external services and repositories:

1. GitHub Pages: Production hosting at docs.celestia.org via CNAME at .github/workflows/deploy.yml57
2. docs-preview Repository: PR preview hosting at celestiaorg/docs-preview requiring PR_PREVIEW_DEPLOY secret at .github/workflows/preview.yaml48
3. GitHub API: Version tag fetching in latest-tags.yaml workflow (referenced but not in provided files)
4. CDN/npm Registry: Dependency installation from registry.npmjs.org via lockfiles

The system maintains strict version locking through yarn.lock at yarn.lock1-2 to ensure reproducible builds across all environments.

Sources: .github/workflows/deploy.yml46-59 .github/workflows/preview.yaml44-78 yarn.lock1-10