The Celestia documentation repository (https://github.com/celestiaorg/docs) is a Next.js-based static site generator that produces the official documentation website at https://docs.celestia.org. The repository uses Nextra, a documentation framework built on Next.js and MDX, to transform markdown content into a fully static, searchable documentation site.
Scope of this document: This page provides a high-level architectural overview of the entire documentation system, including the build pipeline, content structure, and deployment mechanisms. For specific subsystem details, see:
The repository consists of three primary subsystems that work together to produce and deploy the documentation website:
Sources: README.md14 next.config.mjs1-41 package.json1-56
Based on development activity and system criticality, the subsystems rank as follows:
| Subsystem | Importance Score | Key Function |
|---|---|---|
| Deployment System | 257.67 | Automated publishing to production and PR previews |
| Build System | 137.16 | Content processing, validation, and static generation |
| Content Layer | 114.05 | Documentation source files and assets |
Sources: High-level system architecture diagrams (provided in context)
The documentation system is built on the following technologies:
Sources: package.json19-33 package.json36-54
The repository uses Yarn for package management with a frozen lockfile to ensure reproducible builds:
[email protected], [email protected], [email protected]@mdx-js/[email protected], [email protected], [email protected], [email protected]tailwindcss@4, @tailwindcss/postcss@4[email protected] (generates client-side search index)eslint@9, [email protected], [email protected]Sources: package.json19-54 yarn.lock1-8
The repository follows a clear directory structure that separates concerns:
Sources: README.md47-53 README.md117-122
| Directory | Purpose | Key Files |
|---|---|---|
app/ | Documentation content and navigation | **/page.mdx, **/_meta.js |
public/ | Static assets served directly | Images, fonts, PDFs |
constants/ | Shared values for template replacement | mainnet_versions.json, mocha_versions.json |
plugins/ | Custom remark plugins | remark-replace-variables.mjs |
scripts/ | Build utilities and validation | check-links.mjs, generate-llms.js |
.github/workflows/ | CI/CD pipeline definitions | deploy.yml, preview.yml, lint.yaml |
out/ | Build output (generated) | Static HTML, CSS, JS, search index |
Sources: README.md47-53 next.config.mjs25
The documentation system transforms source content into a deployed website through a multi-stage pipeline:
Sources: package.json6-14 .github/workflows/deploy.yml (implied), .github/workflows/preview.yml1-144 .github/workflows/lint.yaml1-53
yarn install --frozen-lockfile ensures reproducible builds with exact dependency versionsyarn generate:llms creates an LLM-friendly text export of all documentationyarn build runs next build --webpack to compile MDX, process templates, and bundle assetspostbuild script runs pagefind --site out --output-path out/_pagefind to generate the client-side search indexSources: package.json6-14 next.config.mjs21-40
The build system behavior is controlled by several configuration files:
Sources: next.config.mjs1-41 package.json1-56 README.md36-45
next.config.mjs - Primary build configuration:
output: 'export' for static site generation (next.config.mjs25)basePath and assetPrefix for subpath deployments (next.config.mjs17-24)remarkReplaceVariables (next.config.mjs4-13)trailingSlash: true for consistent routing (next.config.mjs26)package.json - Scripts and dependencies:
dev: Local development server with webpack (package.json7)build: Production build with webpack (package.json8)postbuild: Automatic search index generation (package.json9)check-links: Link validation utility (package.json14)simple-git-hooks: Pre-push linting enforcement (package.json16-18)Sources: next.config.mjs1-41 package.json6-18
The system supports multiple deployment environments through environment variables:
| Environment Variable | Purpose | Example Value |
|---|---|---|
BASE | Asset prefix with trailing slash | /docs-preview/pr-123/ |
NEXT_PUBLIC_BASE_PATH | Client-side base path (no trailing slash) | /docs-preview/pr-123 |
Production deployment: Both variables are undefined, resulting in root-level deployment at docs.celestia.org
Preview deployment: Set dynamically per PR, enabling subpath deployment at celestiaorg.github.io/docs-preview/pr-N/
Sources: README.md36-45 .github/workflows/preview.yml39-42 next.config.mjs16-24
The repository enforces quality through multiple validation layers:
Sources: package.json16-18 .github/workflows/lint.yaml1-53 scripts/check-links.mjs1-795
Pre-push Hook: Automatically runs npm run lint before pushing to prevent broken code from entering the repository (package.json16-18)
CI Linting: The lint.yaml workflow runs ESLint on every push and PR to validate code style and catch errors (.github/workflows/lint.yaml18-34)
Link Validation: A sophisticated link checker that:
app/ directory structure (scripts/check-links.mjs62-89)Scheduled Checks: Link validation runs weekly to catch external link degradation (.github/workflows/lint.yaml13-15)
Sources: scripts/check-links.mjs1-795 .github/workflows/lint.yaml1-53 package.json16-18
The build process generates several artifacts:
| Artifact | Location | Purpose |
|---|---|---|
| Static HTML/CSS/JS | out/ | Pre-rendered pages and assets for hosting |
| Search Index | out/_pagefind/ | Client-side search database (Pagefind) |
| LLM Export | public/llms.txt | Human-readable documentation export for LLM ingestion |
.nojekyll | out/.nojekyll | Prevents GitHub Pages from running Jekyll processing |
Access URLs:
Sources: README.md12-14 package.json9 .github/workflows/preview.yml63-64
Local development follows this pattern:
yarn install (uses frozen lockfile)yarn dev (runs on http://localhost:3000)app/, update constants in constants/yarn lint and optionally yarn check-linksyarn build && yarn start to test static exportSources: README.md16-34 README.md62-68 package.json6-14
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.