Setup and editing

This guide covers the essential workflows and components for editing Weaviate's documentation. Whether you're adding new content, updating existing pages, or working with interactive components, this reference will help you work effectively with our Docusaurus-based documentation system.

Following these guidelines ensures consistency across the documentation and maintains the quality of the user experience.

Start development server for live editing with hot reload:

yarn start

This launches a local development server, typically at http://localhost:3000, where you can see your changes instantly as you edit files.

Build the documentation for production:

yarn build

This creates an optimized production build in the build/ directory and validates all links, references, and configurations. Always run this before submitting pull requests to catch any issues.

Serve the built documentation locally:

yarn serve

This serves the production build locally, useful for testing the built version before deployment. The site will be available at http://localhost:3000.

The build process performs several important validations:

• Link checking: Verifies all internal links point to existing pages
• Reference validation: Ensures all imports and components are valid
• Markdown processing: Converts MDX to HTML and catches syntax errors
• Plugin execution: Runs plugins like llms.txt generation

Always fix any build errors before submitting changes, as broken builds will prevent deployment.

Use relative paths when linking within the same documentation section:

<!-- Within /weaviate section -->

[Quickstart guide](./quickstart/index.md)

<!-- Within /query-agent section -->

[Query Agent](../index.md)

Use absolute paths for cross-section linking:

<!-- Linking from /weaviate to /query-agent -->

[Query Agent](/query-agent/index.md)

<!-- Linking from /query-agent to /weaviate -->

[Weaviate Database](/weaviate/index.md)

Use absolute URLs for reusable components:

<!-- Linking from _includes/ to /query-agent -->

[Query Agent](/query-agent/quickstart)

This convention ensures links work correctly regardless of where the component is imported.

For internal links in JSX/MDX content, use Docusaurus's Link component instead of HTML <a> tags to enable link checking:

import Link from '@docusaurus/Link';

// Good - enables link validation
<Link to="/weaviate/quickstart">Get started with Weaviate</Link>

// Avoid - bypasses link checking
<a href="/weaviate/quickstart">Get started with Weaviate</a>

The Link component performs validation during build time and will report broken internal links as build errors.

When linking to scalar OpenAPI reference documentation that may not be available during build, use SkipLink to skip validation:

import SkipLink from "/src/components/SkipValidationLink";

<SkipLink href="/weaviate/api/rest#tag/backups">References: REST API: Backups</SkipLink>

This prevents build failures while still providing the correct link to users. Use this sparingly and only for external references that are known to be valid but unavailable during build.

FilteredTextBlock allows you to include specific sections of code files, keeping examples up-to-date with tested code. Use Tabs to provide code examples in multiple languages.

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
import PyCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.py";
import TSCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.ts";
import GoCode from "!!raw-loader!/_includes/code/howto/go/docs/manage-data.aliases_test.go";

<Tabs className="code" groupId="languages">
  <TabItem value="py" label="Python">
    <FilteredTextBlock
      text={PyCode}
      startMarker="# START CreateAlias"
      endMarker="# END CreateAlias"
      language="py"
    />
  </TabItem>
  <TabItem value="ts" label="JavaScript/TypeScript">
    <FilteredTextBlock
      text={TSCode}
      startMarker="// START CreateAlias"
      endMarker="// END CreateAlias"
      language="ts"
    />
  </TabItem>
  <TabItem value="go" label="Go">
    <FilteredTextBlock
      text={GoCode}
      startMarker="// START CreateAlias"
      endMarker="// END CreateAlias"
      language="go"
    />
  </TabItem>
</Tabs>;

Use consistent marker patterns in your source code files:

• Python:
  • # START SectionName
  • # END SectionName
• JavaScript/TypeScript:
  • // START SectionName
  • // END SectionName
• Java:
  • // START SectionName
  • // END SectionName
• Go:
  • // START SectionName
  • // END SectionName

Try to be consistent with the code output in different languages. Instead of language specific objects and terms, try to use primitive values for output.

Most pages need to be manually added to the sidebar configuration to appear in navigation:

// In sidebars.js
{
  type: "doc",
  id: "weaviate/index",
  label: "Introduction",
},
{
  type: "category",
  label: "Quickstart",
  link: {
    type: "doc",
    id: "weaviate/quickstart/index",
  },
  items: ["weaviate/quickstart/local"],
},
{
  type: "link",
  label: "Installation",
  href: "https://docs.weaviate.io/deploy",
},

Some sections use autogenerated sidebars that automatically include all files in a directory:

conceptsSidebar: [
  {
    type: "autogenerated",
    dirName: "weaviate/concepts",
  },
],

Files in autogenerated sections appear automatically but can be ordered using the sidebar_position field in frontmatter.

CardsSection creates interactive card layouts for navigation and feature highlighting:

import CardsSection from "/src/components/CardsSection";

export const welcomeCardsData = [
  {
    id: "new",
    title: "New to Weaviate?",
    description: (
      <>
        Start with the{" "}
        <span className={styles.highlight}>Quickstart tutorial</span> – an
        end-to-end demo that takes 15–30 minutes.
      </>
    ),
    link: "/weaviate/quickstart",
    icon: "fas fa-star", // Font Awesome CSS class
  },
  {
    id: "concepts",
    title: "Core Concepts",
    description:
      "Learn about vector databases, embeddings, and how Weaviate works.",
    link: "/weaviate/concepts",
    icon: "fas fa-brain",
  },
];

<CardsSection items={welcomeCardsData} className={styles.smallCards} />;

Each card object supports:

• id: Unique identifier for the card
• title: Card heading text
• description: Card content (can include JSX)
• link: Destination URL (internal or external)
• icon: Font Awesome CSS class for the icon

Apply custom CSS classes for different card layouts:

• Default large cards
• className={styles.smallCards} - Compact card layout
• Custom CSS classes defined in your component's CSS module

APITable wraps standard markdown tables to make each row clickable and linkable:

import APITable from "@site/src/components/APITable";

;

<APITable>

</APITable>

Check out the source code of this page for an example of how to use the APITable component.

For simple images, use Markdown syntax:

![Simple image](./_includes/image.png)

For images requiring separate light and dark mode variant or CSS adjustments (e.g. width), use the Docusaurus ThemedImage component:

import ThemedImage from "@theme/ThemedImage";
import MyImageLight from "./_img/my_image_light.png";
import MyImageDark from "./_img/my_image_dark.png";

<ThemedImage
  alt="My image alt text"
  sources={{
    light: MyImageLight,
    dark: MyImageDark,
  }}
  width="300"
/>;

Have a question or feedback? Here's how to reach us.