AGENTS.md - StarRocks Documentation

Guidelines for AI coding agents working with StarRocks documentation.

Overview

StarRocks documentation is built using Docusaurus and hosted at https://docs.starrocks.io/. Documentation is available in English, Chinese, and Japanese.

Read handbook/index.md first for repo-wide routing, then use the docs domain map in handbook/domains/docs-and-translation.md for handbook-vs-public-docs boundaries.

Directory Structure

docs/
├── en/                    # English documentation
│   ├── administration/    # Admin guides
│   ├── benchmarking/      # Benchmark guides
│   ├── data_source/       # Data source integration
│   ├── deployment/        # Deployment guides
│   ├── developers/        # Developer guides
│   ├── faq/               # FAQs
│   ├── introduction/      # Introduction
│   ├── loading/           # Data loading
│   ├── reference/         # Reference docs (SQL, config)
│   ├── sql-reference/     # SQL reference
│   └── using_starrocks/   # User guides
├── ja/                    # Japanese documentation (mirrors en/)
├── zh/                    # Chinese documentation (mirrors en/)
├── docusaurus/            # Docusaurus build config
│   ├── docusaurus.config.js
│   ├── sidebars.json      # autogenerated from the directory tree
│   └── src/
└── _assets/               # Shared images and assets

Building Documentation

cd docs/docusaurus

# Install dependencies
npm install

# Start development server
npm start

# Build static site
npm run build

Critical Instructions

Never violate these directives. If a task would require violating them, stop and ask the user for clarification before proceeding:

Do not add information beyond the requested changes.
Do not modify files other than those specified by the user.
Do not change existing frontmatter unless explicitly instructed. Adding required frontmatter fields to a new page or a page that is missing them is allowed.
Do not use training data for StarRocks technical facts. Verify all commands, configuration options, parameter names, and version numbers against existing documentation in the same language directory before writing them. If a technical detail cannot be confirmed from existing docs, list the unconfirmed items and ask the user how to proceed.
When editing a page in en/, zh/, or ja/, update the corresponding pages in the other language directories. If a ja/ page does not yet exist, note this in your completion summary and ask the user whether to create it.
Do not commit or push without explicit confirmation from the user.
When a task attempt fails, try no more than two approaches before stopping to ask for instructions.
When stopping to ask for clarification: state the blocker, list what you have verified or attempted, and ask one specific question. Do not ask multiple questions at once.

Definition of Done

A task is complete when:

All requested changes have been made to the specified files only.
Corresponding pages in all three language directories (en/, zh/, ja/) have been updated, or the user has been informed if a ja/ page does not exist.
A summary of every changed file (with path) has been provided to the user.
The user has been asked whether they are ready to commit and push.

After presenting the completion summary, wait for explicit user instruction before making further changes.

Markdown Conventions

Frontmatter

Every page must open with frontmatter between --- delimiters.

Required:

displayed_sidebar: docs — must be present on every page.
description — one-sentence plain-text summary of the page (under 160 characters). Required on every page except those with unlisted: true. Used by Algolia search snippets and the llms.txt LLM index. No markdown formatting, code spans, or links.

Optional:

sidebar_position — integer controlling sort order within a sidebar category.
sidebar_label — overrides the H1 as the sidebar link text.
toc_max_heading_level — integer (2–6) capping right-side TOC depth.
keywords — list of terms for search and SEO.
unlisted: true — keeps the URL live but hides the page from navigation and search.
hide_table_of_contents: true — removes the right-side TOC.
title — overrides the H1 as the browser tab title and SEO metadata.

Language versions

All three language directories must stay in sync: en/, zh/, and ja/. When editing a page in one language, update the corresponding page in the other two. If a ja/ page does not yet exist, note this in your completion summary and ask whether to create it.

New pages

Create the file under en/, in the directory matching the sidebar section it belongs to.
Set sidebar_position in its frontmatter to place it within that section. There is no sidebar file to edit — see "Sidebar Configuration" below.
Create matching files under zh/ and ja/ at the same relative path.

Code blocks

Always specify a language for fenced code blocks. Never use an unlabeled fence for code that has an identifiable language.

Admonitions

Use Docusaurus syntax — not RST-style directives:

:::note
Supplemental information.
:::

:::tip
Helpful shortcuts or alternatives.
:::

:::warning
Risk of data loss or service disruption.
:::

:::caution
Situations requiring extra care.
:::

Do not stack multiple admonitions directly after one another.

Links

Use relative paths for internal links: [text](../category/page.md). Do not use absolute URLs for pages within the docs site.

Images

Place images in _assets/ and reference with a relative path: ![alt](../_assets/image.png).

Writing Documentation

File Format

Use Markdown (.md) files
Include frontmatter for metadata:

---
displayed_sidebar: docs
keywords: ['keyword1', 'keyword2']
---

# Page Title

Content here...

Style Guidelines

Clear and concise: Use simple language
Code examples: Include runnable examples
Screenshots: Use sparingly, keep updated
Links: Use relative links within docs

Code Blocks

Use fenced code blocks with language:

```sql
SELECT * FROM table WHERE id = 1;
```

```bash
./build.sh --fe --be
```

```java
public class Example {
    public static void main(String[] args) { }
}
```

Images

Place images in _assets/ and reference:

![Description](../_assets/image-name.png)

Contributing Documentation

For New Features

Create doc in the directory matching its sidebar section
Set sidebar_position in its frontmatter to order it within that section
Add English and Chinese versions; add Japanese version when applicable

For Bug Fixes

Create PR with [Doc] prefix in title
Sign off commit: git commit -s
Select "Doc" checkbox in PR template

Translation

When updating English docs, update Chinese docs too (or vice versa). Update Japanese docs when a corresponding docs/ja/ page exists or when explicitly requested:

docs/en/path/to/file.md (required)
docs/zh/path/to/file.md (required)
docs/ja/path/to/file.md (when applicable)

Sidebar Configuration

The sidebar is autogenerated from the directory tree. docs/docusaurus/sidebars.json contains only:

{ "docs": [ { "type": "autogenerated", "dirName": "." } ] }

Do not add page entries to it. The shape of the sidebar comes from two places instead:

Directory layout — every directory under en/ becomes a sidebar category, and every page becomes an item in the category matching its directory.

_category_.yml — one per category directory, setting that category's label, its order among its siblings, and what its title links to:

position: 80
label: 'Data Loading'
collapsible: true
collapsed: true
link:
  type: doc
  id: loading

link is either type: doc with the id of a page inside that directory, or type: generated-index for an auto-built listing page. Omit link entirely for a category whose title is not clickable.

Category index pages use the <dir>/<dir>.md convention: loading/loading.mdx is the index for loading/ and is served at /docs/loading/. Docusaurus removes it from the item list automatically, so it does not appear twice.

Ordering within a category comes from each page's sidebar_position frontmatter (existing pages are spaced by 10, so use the gaps). Pages without it sort last, alphabetically.

Keep _category_.yml files in sync across en/, zh/, and ja/. Translated category labels live in docusaurus/i18n/<locale>/docusaurus-plugin-content-docs/current.json, keyed by the English label.

Moving or renaming a page

Changing a page's path changes its URL. Add a redirect to the MOVED_DOCS list at the top of docs/docusaurus/docusaurus.config.js; entries there feed both the client-redirects plugin and the LLM-index exclusions. The same list must be mirrored in the doc-build repo's docusaurus.config.js, which is what the published site uses.

Common Tasks

Add New Page

Create docs/en/category/new-page.md in the directory for its sidebar section
Set sidebar_position in its frontmatter
Create Chinese version docs/zh/category/new-page.md
Create Japanese version docs/ja/category/new-page.md (when applicable)

Update Existing Page

Edit the markdown file
Update all language versions if needed
Verify links still work

Add Code Example

## Example

Here's how to create a table:

```sql
CREATE TABLE example (
    id INT,
    name STRING
)
DISTRIBUTED BY HASH(id);


## Preview Changes

```bash
cd docs/docusaurus
npm start
# Open http://localhost:3000

Developer Documentation

Developer-specific docs are in docs/en/developers/:

code-style-guides/ - Coding standards
development-environment/ - Setup guides
build-starrocks/ - Build instructions

Best Practices

Keep it updated: Update docs when code changes
Test examples: Verify code examples work
Use templates: Follow existing page structure
Cross-reference: Link related topics
Version awareness: Note version-specific features

License

Documentation is under Apache 2.0 license.

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md - StarRocks Documentation

Overview

Directory Structure

Building Documentation

Critical Instructions

Definition of Done

Markdown Conventions

Frontmatter

Language versions

New pages

Code blocks

Admonitions

Links

Images

Writing Documentation

File Format

Style Guidelines

Code Blocks

Images

Contributing Documentation

For New Features

For Bug Fixes

Translation

Sidebar Configuration

Moving or renaming a page

Common Tasks

Add New Page

Update Existing Page

Add Code Example

Developer Documentation

Best Practices

License