This repository contains the documentation for Weaviate (vector database), Weaviate Cloud, and Query Agent. It's built with Docusaurus 3.

If you want to contribute to the documentation, follow these steps to get your local development environment set up.

# Install Node.js 22 and yarn
nvm install 22 && nvm use 22
npm install --global yarn

# Install dependencies and start dev server
yarn install
yarn start  # Opens http://localhost:3000

To make any changes to the documentation, edit the files in the /docs directory. The documentation is written in MDX, which allows you to use React components within markdown files.

Documentation lives in the /docs directory and maps directly to site URLs:

The docs are in the following directories:

• /docs/weaviate/ → Main database documentation
• /docs/deploy/ → Deployment documentation
• /docs/cloud/ → Weaviate Cloud docs
• /docs/query-agent/ → Query Agent docs

They are rendered using the following mapping files:

• secondaryNavbar.js → Top navigation bar (add new sections here)
• sidebars.js → Navigation structure (add new pages here to appear in sidebar)

Code examples use the FilteredTextBlock component to extract sections from full, runnable code files:

1. Code files live in _includes/code/ or nested within doc directories (e.g., docs/weaviate/tutorials/_includes/)
2. Mark sections in code files with comments:

   # START SectionName
   # Your code here
   # END SectionName

3. Import and display in MDX files:

   import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
   import PyCode from "!!raw-loader!/_includes/code/example.py";
   
   <FilteredTextBlock
     text={PyCode}
     startMarker="# START SectionName"
     endMarker="# END SectionName"
     language="py"
   />

This keeps code DRY and ensures examples are tested as complete, runnable scripts.

Run these checks locally to ensure your changes are ready:

# 1. Validate internal links
yarn build-dev
yarn validate-links-dev

# 2. Optional: Test affected code examples (if you modified code snippets)
# See README-tests.md for language-specific test commands
pytest tests/test_your_changes.py  # Python examples

Pre-submission checklist:

• Links validated (no broken internal links)
• Code examples tested (if applicable)
• Changes preview correctly in local dev server (yarn start)
• No merge conflicts with main

• Create a PR against the main branch
• At least one maintainer review is required before merging
• The documentation site automatically rebuilds and deploys on every push to main

• Questions or stuck? Open a GitHub issue or discussion
• Found a bug? Check existing issues first, then create a new one with details

Weaviate uses Docusaurus 3 to build our documentation. Docusaurus is a static website generator that runs under Node.js. We use a Node.js project management tool called yarn to install Docusaurus and to manage project dependencies.

If you do not have Node.js and yarn installed on your system, install them first.

Use the nvm package manager to install Node.js. The nvm project page provides an installation script.

After you install nvm use it to install Node.js.

nvm install

By default, nvm installs the most recent version of Node.js. Also install the version of Node.js that is specified in .github/workflows/pull_requests.yaml. At the time of writing it is version v22.12.0.

nvm install 22
nvm use 22

Node.js includes the npm package manager. Use npm to install yarn.

npm install --global yarn

Once you have a local copy of the repository, you need to install Docusaurus and the other project dependencies.

Switch to the project directory, then use yarn to update the dependencies.

yarn install

You may see some warnings during the installation.

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

yarn start

Open http://localhost:3000/ showing the local build. If you close the terminal, the server will stop. Or press Ctrl+C/Cmd+C to stop the server.

This command generates static content into the build directory. You can use a hosting service to serve the static content.

yarn build

The build command is useful when you are finished editing. If you ran yarn start to start a local web server, you do not need to use yarn build to see you changes while you are editing.

This command generates static content into the build directory and can be served using any static contents hosting service.

Understanding the repository structure will help you navigate and contribute effectively:

• /docs - Main documentation content (MDX files)

  • weaviate/ - Database documentation with 26+ subdirectories (API, concepts, guides, search, etc.)
  • cloud/ - Weaviate Cloud Services documentation
  • agents/ - AI agents framework documentation
  • deploy/ - Deployment guides
  • Note: /integrations was removed in Dec 2025; integration pages now live on the main Weaviate site

• /_includes - Reusable content fragments

  • Code snippets organized by language
  • Configuration files
  • Images and other shared assets
  • Used via imports in MDX files to avoid duplication

• /src - Custom React components and theme customizations

  • components/ - 16+ custom components (Feedback, InPageAskAI, APITable, FilteredTextBlock, etc.)
  • theme/ - Docusaurus swizzled components (Navbar, Footer, SearchBar, etc.)
  • css/ - SCSS stylesheets (~2,900 lines in custom.scss)
  • remark/ - Custom remark plugins for markdown processing

• /_build_scripts - Build automation and validation

  • update-config-versions.js - Fetches latest versions from GitHub
  • validate-links-*.js - Link validation for PRs
  • publish-*.sh - Netlify deployment scripts
  • slack-*.sh - Slack notification scripts

• /tests - Python test suite with Docker Compose configs

• /tools - Python utilities for content validation and transformation

• /static - Static assets (images, fonts, JavaScript files)

• docusaurus.config.js - Main Docusaurus configuration
• docusaurus.dev.config.js - Dev config (removes redirects, adds trailing slashes for link validation)
• sidebars.js - Sidebar navigation structure (~1000 lines defining doc hierarchy)
• secondaryNavbar.js - Multi-level secondary navigation configuration
• versions-config.json - Dynamic version references for Weaviate ecosystem
• netlify.toml - Deployment config with 100+ URL redirects

The site uses a multi-level navigation architecture:

1. Primary navigation - Top navbar with main sections (Build/Database, Cloud, Agents, Integrations)
2. Secondary navigation (secondaryNavbar.js) - Dropdown menus that swap the active sidebar
3. Sidebars (sidebars.js) - Multiple named sidebars for different documentation sections

The custom navbar (src/theme/Navbar/NavbarWrapper.js) provides:

• Sticky positioning
• Modal navigation for quick section switching
• Keyboard shortcuts (Cmd+U on Mac)
• State management via custom hooks

To add new pages to navigation:

1. Add the page to the appropriate sidebar in sidebars.js
2. If creating a new section, update secondaryNavbar.js

Version numbers are maintained in versions-config.json and automatically updated at build time via _build_scripts/update-config-versions.js (fetches from latest GitHub releases).

Use version variables in MDX files instead of hardcoding:

Install version ||site.weaviate_version||

This prevents version numbers from becoming stale across the documentation.

Custom components are located in src/components/. Key components include:

• FilteredTextBlock - Extracts and displays sections from code files (most commonly used)
• Feedback - Expandable feedback widget linking to GitHub issues
• APITable - Structured API parameter tables
• DockerConfigGen - Interactive Docker configuration generator
• DocsImage - Enhanced image component with validation
• SkipValidationLink - Links exempt from validation

To use a component in MDX:

import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
import PyCode from "!!raw-loader!/_includes/code/example.py";

<FilteredTextBlock
  text={PyCode}
  startMarker="# START SectionName"
  endMarker="# END SectionName"
  language="py"
/>

Register new MDX components in src/theme/MDXComponents.js.

Code examples in _includes/code/ are validated via automated tests to ensure they work correctly. This includes:

• Python tests via pytest
• Java tests via Maven
• Go tests via go test
• Docker Compose configs for spinning up Weaviate test instances

For complete testing documentation, see README-tests.md.

# Start Weaviate test instances
tests/start-weaviate.sh

# Python tests
pytest
pytest tests/test_quickstart.py  # Specific file

# Stop Weaviate test instances
tests/stop-weaviate.sh

Before PRs are merged, internal links are validated to prevent broken links:

# Build dev site (with trailing slashes for validation)
yarn build-dev

# Validate links
yarn validate-links-dev

Use the <SkipValidationLink> component for intentionally external or placeholder links.

• Production: Deployed to docs.weaviate.io via Netlify
• PR Previews: Automatic preview builds for all pull requests
• Redirects: Managed in netlify.toml (100+ legacy URL mappings)
• Auto-deployment: Site automatically rebuilds and deploys on every push to main

The site uses several plugins and integrations:

• Kapa.ai - AI chatbot widget (configured in Root.js)
• Scalar - Interactive REST API documentation at /weaviate/api/rest
• Google Tag Manager - Analytics
• LLMs.txt plugin - Generates LLM-friendly content dump
• Mermaid - Diagram support in markdown

Swizzled Docusaurus components in src/theme/:

• Root.js - App-level wrapper (manages Kapa.ai widget, first-visit modal)
• Navbar/ - Custom navbar with secondary nav and modal
• DocItem/ - Document page customizations
• SearchBar/ - Custom search implementation

Styling in src/css/:

• custom.scss - Main styles
• Theme variables for light/dark mode
• Component-specific styles