This is the documentation website for Apache Ignite 3, built using Docusaurus, a modern static website generator.
This documentation site is currently being migrated from Jekyll + AsciiDoc to Docusaurus + Markdown/MDX as part of JIRA ticket IGNITE-26681.
Migration Progress: Sections 1-8 Complete (Environment, Navigation, Conversion Agent, Content Conversion)
All 86 documentation files have been converted from AsciiDoc to Markdown/MDX. See IGNITE-26681/docusaurus-migration-project-plan.md for detailed migration plan and progress tracking.
Navigate to the docs directory and install dependencies:
cd docs
npm install
For a clean install (recommended for CI/CD or when troubleshooting):
npm ci
Note: All npm commands in this guide should be run from the docs/ directory.
Start the development server from the docs/ directory:
npm start
This command:
http://localhost:3000/docs/ignite3/http://192.168.1.x:3000/docs/ignite3/)What you'll see:
Cmd+K or Ctrl+K)For faster startup during active development:
npm run start:fast
The development server is accessible on your local network via your IP address (e.g., http://192.168.1.x:3000/docs/ignite3/).
Build the site for production:
npm run build
This generates static content into the build directory. The build output can be served using any static web hosting service.
For a full production build with TypeScript validation:
npm run build:prod
For faster builds during testing (without minification):
npm run build:fast
IMPORTANT: You must build the site before serving it. The search functionality requires the build step to generate search indexes.
Build and serve in one command (recommended):
npm run serve:build
Or build and serve separately:
npm run build
npm run serve
The production build will be available at http://localhost:3000/docs/ignite3/.
Validate documentation quality before committing:
Runs TypeScript checks, link validation, and image validation:
npm run validate:quick
Runs all validations including production build:
npm run validate
Check internal links:
npm run check:links
Check image references and alt text:
npm run check:images
Validate production build output:
npm run check:build
TypeScript type checking:
npm run typecheck
docs/ ├── docs/ # Current version documentation (3.1.0) │ └── *.md, *.mdx # Documentation pages ├── versioned_docs/ # Archived versions │ └── version-3.0.0/ # Version 3.0.0 documentation ├── static/ # Static assets │ └── img/ # Images and icons ├── src/ │ ├── components/ # React components │ ├── css/ # Custom CSS │ │ └── custom.css # Theme customization │ └── pages/ # Custom pages ├── scripts/ # Validation scripts │ ├── check-links.js # Link validation │ ├── check-images.js # Image validation │ └── check-build.js # Build validation ├── build/ # Production build output (generated) ├── docusaurus.config.ts # Site configuration ├── sidebars.ts # Navigation structure ├── package.json # Dependencies and scripts └── tsconfig.json # TypeScript configuration
Main configuration is in docusaurus.config.ts:
Sidebar navigation is configured in sidebars.ts.
Custom styles are in src/css/custom.css:
The site supports multiple documentation versions. Version 3.1.0 is the current version.
To create a new version:
npm run docusaurus docs:version 3.2.0
See IGNITE-26681/versioning-workflow.md for detailed versioning procedures.
Search is implemented using @easyops-cn/docusaurus-search-local, providing local search without external dependencies (ASF-compliant).
IMPORTANT: Search indexes are generated during the build process. You must run npm run build before the search functionality will work in production builds.
Search features:
Cmd+K (Mac) or Ctrl+K (Windows/Linux)Mermaid diagrams are supported via @docusaurus/theme-mermaid:
```mermaid graph TD; A-->B; A-->C; ```
Supported diagram types: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, git graphs, pie charts.
Railroad diagrams (syntax diagrams) are supported via a custom React component using the railroad.js library. This component preserves the ability to create clickable links within diagrams for navigation between SQL grammar rules.
Component Location: src/components/RailroadDiagram/
Usage:
--- title: My SQL Reference Page --- import RailroadDiagram from '@site/src/components/RailroadDiagram'; ## CREATE TABLE <RailroadDiagram> {` Diagram( Terminal('CREATE'), Terminal('TABLE'), Optional(Terminal('IF NOT EXISTS')), NonTerminal('table_name', {href:'./grammar-reference/#qualified_table_name'}), Terminal('('), NonTerminal('column_definition', {href:'./grammar-reference/#column_definition'}), Terminal(')') ) `} </RailroadDiagram>
Key Features:
Terminal(), NonTerminal(), Optional(), Sequence(), Choice(), Skip(), OneOrMore(), ZeroOrMore(), Comment()href parameter on NonTerminal() and Terminal()Important Notes:
{ ... } to wrap the diagram codeDiagram() function automatically adds Start() and End() (don't include them unless using ComplexDiagram())Examples: See docs/sql/reference/ddl.mdx, docs/sql/reference/dml.mdx, and docs/sql/reference/grammar-reference.mdx for 52 railroad diagram examples with clickable links.
Prism.js provides syntax highlighting for:
Light theme: GitHub Dark theme: Dracula
Use tabs to show code examples in multiple languages:
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; <Tabs groupId="programming-language"> <TabItem value="java" label="Java"> ```java // Java code ``` </TabItem> <TabItem value="csharp" label="C#"> ```csharp // C# code ``` </TabItem> </Tabs>
The groupId enables tab synchronization across the page.
If you encounter build issues, clear the cache:
npm run clear
If the development server becomes unresponsive:
pkill -f "docusaurus start" npm start
If validation scripts report errors:
Check TypeScript errors without building:
npm run typecheck
The documentation build can be integrated into CI/CD pipelines using the validation scripts.
Example CI workflow:
npm ci # Install dependencies npm run typecheck # Type check npm run check:links # Validate links npm run check:images # Validate images npm run build:prod # Production build npm run check:build # Validate build output
See IGNITE-26681/build-scripts-documentation.md for detailed CI/CD integration examples including GitHub Actions and TeamCity configurations.
Additional documentation for this project:
When contributing documentation changes:
npm run validate:quick before committingnpm startFor issues related to the documentation site:
This documentation is licensed under the Apache License 2.0. See the project root for license details.