wyuc 77bcd589e0
docs: add Fumadocs documentation site (#622)
* docs: add Fumadocs documentation site (packages/docs)

Static-exportable Fumadocs site for the OpenMAIC docs, served under /docs.
- 6 locales (en default + zh-CN/zh-TW/ja/ru/ar) with Arabic RTL
- English unprefixed (/docs/getting-started) to preserve legacy URLs;
  other locales at /docs/<lang>/<slug>
- Orama static search compatible with `output: 'export'`
- Brand theming via CSS variables; "Live Demo" link back to open.maic.chat

Kept fully isolated from the main app so it does not affect its build or CI:
- excluded from the pnpm workspace (own lockfile, build and deploy)
- ignored in .prettierignore (own toolchain, like the other packages)
- excluded from the root tsconfig so the main app build does not type-check it
ESLint already ignores packages/**.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* ci: add standalone docs build check

Validate that packages/docs still builds (next build + static export) on
PRs that touch it. Runs only on packages/docs changes; no secrets, no deploy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: address CR — CJK search, single-source locale config

- Fix Chinese/Japanese search: zh-CN/zh-TW use the mandarin tokenizer and ja
  the japanese tokenizer (@orama/tokenizers) on both the build-time index and
  the client query; the english whitespace tokenizer indexed CJK as one token.
- Add lib/locales.mjs as the single source for the locale list, default locale,
  per-locale search tokenizer, RTL set, labels, and the /docs basePath; consume
  it from i18n, the search index/dialog, next.config, and the postexport script
  (was duplicated and drift-prone).
- Drop dead gitConfig.branch; fix the stale README route table; document the
  English-nested-page limitation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-05-31 00:11:17 +08:00

2.7 KiB

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

The site is mounted under the /docs basePath, so open http://localhost:3000/docs in your browser.

Build the static site (next build + static export, output in out/):

pnpm build

Explore

In the project, you can see:

  • lib/locales.mjs: Single source of truth for locales — language list, default locale, per-locale search tokenizer, RTL set, labels, and the /docs basePath. Plain JS so the scripts/postexport.mjs build step can import it too.
  • lib/source.ts: Content source adapter, loader() wires the MDX content with i18n.
  • lib/layout.shared.tsx: Shared layout options (nav, GitHub link, Live Demo link).
Route Description
app/(en) English (default locale), served unprefixed at /docs/<slug>.
app/(intl)/[lang] Other locales, served at /docs/<lang>/<slug>.
app/static.json/route.ts Build-time Orama static search index (served at /docs/static.json).
scripts/postexport.mjs Post-build step: per-locale index redirects + English alias stubs.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Known limitations

English supports only top-level docs pages

The default locale (en) is served unprefixed (/docs/getting-started). To keep it unprefixed without the hydration conflict that a catch-all two-route-group split causes, the English route app/(en)/[slug] is a single (non-catch-all) segment. As a result, nested English pages would 404 — e.g. content/docs/guides/intro.mdx resolves for every other locale (their routes are catch-all under app/(intl)/[lang]/[...slug]) but not for English.

Only top-level English docs pages work today. Adding nested English docs requires revisiting the (en) route group (and resolving the hydration conflict that the current split avoids); this is deliberately deferred.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: