npm package: @llamaindex/docs
Description: 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](https://developers
Latest version: 0.12.0

# @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](https://developers.llamaindex.ai).

## Quick start

From your source repo root (e.g. `llama_index`):

```bash
# 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.

```js
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:
  ```js
  { type: "autogenerate", directory: "python/framework", collapsed: true }
  ```
- **`items`** — Manually specified sidebar items:
  ```js
  { 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.

```yaml
# 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:

```yaml
---
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`:

```js
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.