Celestia documentation

Welcome to the official documentation repository for Celestia.

• Live site: https://docs.celestia.org
• LLMs.txt: https://docs.celestia.org/llms.txt
• Built with: Next.js + Nextra (MDX), exported as a static site.

Local development

Prereqs: Node.js 20+ and Yarn.

yarn install
yarn dev

Open http://localhost:3000

Build & preview the static export

next.config.mjs is configured for static export (output: 'export'). Builds write to out/ and generate a Pagefind search index in out/_pagefind/.

yarn build
yarn start

Base paths (deploying under a subpath)

For deployments that live under a subdirectory (e.g. GitHub Pages previews), set:

• BASE with a trailing slash (used for assetPrefix)
• NEXT_PUBLIC_BASE_PATH without a trailing slash (used by client-side components for asset URLs)

BASE=/docs-preview/new_docs/ NEXT_PUBLIC_BASE_PATH=/docs-preview/new_docs yarn build

Content & structure

• app/**/page.mdx: documentation pages
• app/**/_meta.js: sidebar order/titles
• public/: static assets
• constants/*.json: shared values referenced in MDX (e.g. {{mainnetVersions['app-latest-tag']}}), replaced by plugins/remark-replace-variables.mjs

Useful scripts

• yarn lint: lint the codebase (also runs on git push via hook)
• yarn check-links -- --all: validate internal + external links (see scripts/check-links.mjs --help)
• yarn generate:llms: generate public/llms.txt (ignored by git) for ingestion tools/LLMs

Contribution guidelines

We love contributions from the community! Whether you're fixing typos, improving clarity, or adding new topics, every contribution helps.

• Fork & clone: fork this repository and clone it locally
• Branch: create a new branch for your changes
• Commit: use clear, concise commit messages
• PR: push to your fork and open a pull request

Please review the full contribution guidelines before opening a PR: https://github.com/celestiaorg/.github/blob/main/CONTRIBUTING.md#external-contributions

Documentation standards

This section outlines the standards and guidelines for maintaining consistent, high-quality documentation across the Celestia project.

Styling rules

• Sentence case: use sentence case for headings and titles (reference: #161)
• No “click here”: avoid using “click here” for link text (reference: #1073)
• International English: use international (common) English spelling and terminology
• Network names: use “Arabica devnet”, not “Arabica Devnet”
• Node types: use lowercase for node types (e.g., “bridge node”, not “Bridge Node”)
• Politeness: avoid using “please” in instructional content
• Unique headings: ensure no duplicate headings within a document
• Network references: use “Coffee Beta” network (note the specific capitalization)
• Latin abbreviations: use italicized i.e. or e.g. instead of plain i.e. or e.g.
• Code references: use “celestia-app” in regular text (not inline code) when referring to the application name
• Tab ordering: when using tabs, order them as: Coffee Beta, Mocha, Arabica
• Placeholders: use angle brackets with underscores for placeholders: <flag_name> not <flag-name> or <flag name>

Documentation update procedures

When updating documentation:

1. Run automation: execute any available automation tools before manual updates
2. Chain ID updates: if there are chain-id breaking changes:
   • Update all chain-id references throughout the documentation
   • Search comprehensively to ensure no references are missed
   • Reference example: https://github.com/celestiaorg/docs/pull/857/files#diff-7c3322aa40bebbde7be394c354f900d6b5606eabbd03ac0d661f7565fcadcb70
3. Release notes review: read release notes to identify and implement breaking changes that affect documentation
4. Process reference: documentation update process video: https://www.loom.com/share/0d6897939b654b60b766887b37f86790

Documentation requirements for software

All software documentation must include:

• Proof of functionality (passing CI checks, manual testing evidence, block explorer links where applicable)
• Comprehensive setup (complete setup and usage instructions)
• Troubleshooting (common issues and solutions)
• Version compatibility (clearly state supported versions)

Link format guidelines

When adding internal links to documentation, use root-relative links with an optional section anchor: [link text](/path/to/page/#section-id)

Directory structure

• app/learn: learn about Celestia
• app/build: build on Celestia (including API/RPC references)
• app/operate: run and maintain nodes and infrastructure

Deployment

GitHub Actions workflows in .github/workflows/ build the site and publish out/ for production and preview deployments.

Feedback & suggestions

If you find any discrepancies or have suggestions, please open an issue in this repository.