@llamaindex/docs

Portable docs preview for LlamaIndex source repos. Run npx @llamaindex/docs dev from any configured repo to get a pixel-accurate local preview using the same Astro + Stainless stack as the production site at developers.llamaindex.ai.

Quick start

From your source repo root (e.g. llama_index):

# 1. Create a config file (or write one manually)
npx @llamaindex/docs init

# 2. Edit docs.config.mjs to match your repo layout

# 3. Start the preview server
npx @llamaindex/docs dev

The dev server starts at http://localhost:4321. Edits to your markdown files hot-reload in the browser.

How it works

When you run llamaindex-docs dev, the CLI:

1. Reads docs.config.mjs from your repo root
2. Copies a complete Astro project template into .docs-preview/ (cached between runs)
3. Symlinks your content directories into the template's content tree
4. Runs pnpm install (first run only) then astro dev

The .docs-preview/ directory is disposable — delete it any time. Add it to .gitignore.

Configuration: docs.config.mjs

Create this file at your repo root. It tells the CLI where your content lives and how to render the sidebar.

export default {
  // Unique section identifier — must match the ID used in the production site
  section: "llama-index",

  // Display label shown in the sidebar and page title
  label: "LlamaIndex Framework",

  // Maps local content directories to their URL path in the site.
  // src: path to your markdown/MDX files (relative to repo root)
  // dest: URL prefix — this determines the route structure
  content: [
    { src: "./docs/src/content/docs/framework", dest: "python/framework" },
  ],

  // Sidebar configuration — controls the navigation tree
  sidebar: [
    {
      label: "LlamaIndex Framework",
      content: {
        type: "autogenerate",       // auto-builds sidebar from directory structure
        directory: "python/framework", // must match the dest above
        collapsed: true,
      },
    },
  ],

  // Optional: link to API reference docs (shown as sidebar append)
  apiReferenceLink: "/python/framework-api-reference/",
};

Config fields

| Field | Required | Description | |---|---|---| | section | Yes | Unique section ID (e.g. "llama-index", "llama-cloud") | | label | Yes | Display name (e.g. "LlamaIndex Framework") | | content | Yes | Array of { src, dest } mappings from local dirs to URL prefixes | | sidebar | Yes | Array of sidebar group configs | | apiReferenceLink | No | URL to API reference docs |

Sidebar content types

Each sidebar entry has a label and a content object:

• autogenerate — Builds the sidebar tree from the directory structure automatically:

  { type: "autogenerate", directory: "python/framework", collapsed: true }

• items — Manually specified sidebar items:

  { type: "items", items: [{ label: "Overview", link: "/python/framework/" }] }

Content directory structure

Source repos should keep their docs content nested under a path that reflects the production URL structure. This prevents path collisions when multiple repos contribute to the same site.

Recommended layout:

my-repo/
├── docs.config.mjs              # CLI config (repo root)
├── .gitignore                   # Add .docs-preview/
└── docs/
    └── src/
        └── content/
            └── docs/
                └── framework/   # Your actual markdown content
                    ├── _meta.yml
                    ├── index.md
                    ├── getting_started/
                    │   ├── _meta.yml
                    │   └── installation.md
                    └── guides/
                        └── ...

The framework/ directory name here matches the last segment of the dest path (python/framework). Pages render at URLs like /python/framework/getting_started/installation/.

_meta.yml files

These optional files control sidebar ordering, labels, and collapsed state within a directory. They are processed by the starlight-auto-sidebar integration.

# docs/src/content/docs/framework/getting_started/_meta.yml
label: Getting Started
order: 1
collapsed: false

Frontmatter

Standard Starlight frontmatter is supported in markdown files:

---
title: Installation
sidebar:
  order: 1
---

CLI reference

llamaindex-docs dev

Start a local preview server.

Options:
  -p, --port <port>  Port number (default: 4321)

llamaindex-docs init

Scaffold a docs.config.mjs template in the current directory.

Multiple content directories

If your repo contributes content to multiple URL prefixes, list them all in content:

export default {
  section: "llama-index",
  label: "LlamaIndex Framework",
  content: [
    { src: "./docs/src/content/docs/framework", dest: "python/framework" },
    { src: "./docs/src/content/docs/examples", dest: "python/examples" },
  ],
  sidebar: [
    {
      label: "LlamaIndex Framework",
      content: { type: "autogenerate", directory: "python/framework", collapsed: true },
    },
    {
      label: "Examples",
      content: { type: "autogenerate", directory: "python/examples", collapsed: true },
    },
  ],
};

Troubleshooting

"No docs.config.mjs found" — Run the command from your repo root, not from inside docs/.

Port already in use — Use --port to pick a different port: npx @llamaindex/docs dev --port 4322

Stale preview — Delete .docs-preview/ and re-run. The CLI will recreate it from the template.

Missing content — Check that your content[].src paths point to existing directories. The CLI warns if a source directory doesn't exist.