nocobase/docs

NocoBase Documentation

The documentation site, built with Rspress. It is a workspace package (@nocobase/docs), so pnpm install at the repository root installs its dependencies along with everything else.

pnpm --filter @nocobase/docs dev
pnpm --filter @nocobase/docs build

--lang

Each language is built as a separate site: en is served from / and every other language from /<lang>/. The language is selected by --lang or by the DOCS_LANG environment variable, defaulting to en.

pnpm --filter @nocobase/docs dev --lang=cn
pnpm --filter @nocobase/docs build --lang=cn
pnpm --filter @nocobase/docs preview --lang=cn
pnpm --filter @nocobase/docs build --lang=all

The site framework carries translations for cn / en / ja / es / pt / de / fr / ru / id / vi, but only the languages that have a directory under docs/ are actually built. Today that is cn and en; adding a language is a matter of creating its directory.

--check-dead-links

Dead-link checking is on by default during build and covers links in Markdown bodies. Links in frontmatter — the home page hero actions and feature cards — are not checked, so a route named there can be missing without failing the build.

pnpm --filter @nocobase/docs build --lang=en --check-dead-links=false

Structural checks

check.sh runs the same structural checks CI does: file-tree, _meta.json, _nav.json and home-page alignment across languages, plus bloated-file and deprecated-reference detection. cn is the baseline every other language is compared against.

./check.sh
./check.sh --lang=es
gh pr view <pr> --json files --jq '.files[].path' | ./check.sh --with-i18n-coverage

scripts/README.md documents each script individually.

Documentation AI assistant

The documentation assistant calls an independent Rust backend from the docs-ai-service repository. The backend searches and verifies live pages under docs.nocobase.com; the documentation build does not generate a local AI index. With DOCS_AI_API_URL unset the assistant renders but has nothing to call, which is the expected state for local documentation work.

cd <path-to-docs-ai-service>
cargo run

cd <path-to-nocobase3>
DOCS_AI_API_URL=http://127.0.0.1:3100 pnpm --filter @nocobase/docs dev --lang=cn

Configure the backend for the approved DeepSeek online search provider before starting it. The UI always displays server-provided official citations and renders answer text without raw HTML.

Toolchain

Prettier is the repository baseline, @nocobase/dev-config/prettier. ESLint is this package's own flat config, with eslint-plugin-react-hooks covering hook dependency lists, conditionally called hooks, and missing list keys. Both should report nothing.

pnpm --filter @nocobase/docs lint
pnpm --filter @nocobase/docs format

theme/components/{Nav,NavHamburger,NavScreen,Search,HomeHero} are vendored from Rspress's ejectable theme and excluded from both tools. They are kept byte-for-byte so that a Rspress upgrade is a diff against the new upstream copy; formatting or lint-fixing them destroys that. Fix a problem in one of them upstream and re-copy. Search/SearchPanel.tsx and Search/SuggestItem.tsx do carry deliberate local changes, each with a header naming them.

The exclusion is spelled out in three places, and adding a sixth vendored directory means editing all three:

Where	Covers
eslint.config.mjs, VENDORED_FROM_RSPRESS	ESLint, wherever it runs from
.prettierignore	Prettier run inside this directory
the repository root .prettierignore	Prettier run from the repository root — the pre-commit hook and pnpm format:all

The pre-commit hook runs this package's own ESLint because lint-staged.config.mjs at the repository root lists docs in SELF_LINTING_DIRECTORIES. Without that entry it would run the root ESLint, which matches nothing here and would exit zero without checking anything.

eject rspress components

Customize the theme by ejecting the components. After ejecting, you can find the components in ./theme/components and modify them as you like.

pnpm --filter @nocobase/docs eject <ComponentName>

demo preview

Use @docs/* to import demo components; the alias resolves to docs/ at build time.

import { HelloModel } from '@docs/cn/flow-engine/_demos/HelloModel';

Then use the demo component in the markdown file:

```tsx file="./_demos/flow-model-renderer.tsx" preview

```