UniRL Docs Site

This directory contains the Fumadocs + Next.js documentation site. It is isolated from the Python package so Node dependencies and generated files do not affect framework installs.

Commands

npm ci
npm run docs:check
npm run sync:readmes
npm run dev
npm run build
npm run typecheck

npm run docs:check regenerates README references and checks local Markdown/MDX page links, recognizable heading fragments, relative or public/ static assets, navigation targets, retired names, and explicit repository paths against the framework checkout. It does not crawl external URLs or validate prose semantics.

npm run sync:readmes regenerates English package-reference pages from the official framework README files. Chinese routes use Fumadocs' English fallback for these generated references instead of presenting English text as a Chinese translation. Sync also runs automatically before dev, build, and typecheck.

npm run build statically exports the site to out/. The build also generates .source/, which backs the collections/server import used by Fumadocs MDX.

Framework source of truth

Commands, package READMEs, and recipe paths come from Tencent-Hunyuan/UniRL, while this repository owns the Fumadocs site and GitHub Pages deployment. Point local validation at a current framework checkout:

export UNIRL_SOURCE_ROOT=../UniRL
export UNIRL_SYNC_STRICT=1
npm run docs:check
npm run typecheck
npm run build

CI and deployment check out the official framework separately and use strict sync. When the framework provides docs/reference-manifest.json, the checker validates every listed entrypoint and default recipe, exported algorithm module, model bundle, and recipe. Older framework checkouts use a source-discovered fallback instead of a second hand-maintained inventory. Missing configured README sources fail before generated pages are changed. A deliberate docs-only preview may use UNIRL_SYNC_STRICT=0 npm run sync:readmes.

The pull-request and deployment workflows synchronize README references once, then use ci:typecheck and ci:build to suppress the normal pretypecheck/prebuild synchronization hooks. Local typecheck and build retain those hooks so they also work when run independently.

Structure

Path	Purpose
app/	Next.js App Router pages and static route handlers
content/docs/	MDX source pages and meta.json sidebar ordering
lib/source.ts	Fumadocs loader source
lib/get-llm-text.ts	Markdown conversion for agent endpoints
components/mdx.tsx	MDX component mapping
source.config.ts	Fumadocs MDX collection config
scripts/sync-readme-reference.mjs	Generates embedded package pages from near-code README files

Agent Endpoints

Static builds expose:

• /llms.txt for a compact documentation index.
• /llms-full.txt for the full Markdown corpus.
• /md/<slug>/index.md for one page as Markdown, for example /md/configuration/hydra/index.md.
• /api/search.json for the static search index consumed by Fumadocs UI.

Generated package pages are included in these outputs after npm run sync:readmes.

Keep these routes extension-safe so static hosts can infer MIME types without custom server configuration.

Agent endpoints intentionally read only the English source (content/docs/en). Chinese pages are for human reading and are not included in /llms-full.txt or /md/<slug>/index.md.

Do not add llms.txt as a docs sidebar category. The rendered Agents section explains how agents should navigate the docs; /llms.txt and related routes stay as root-level machine-readable endpoints.

Human Languages

Human documentation is language-prefixed:

• /en/docs for English.
• /zh/docs for Chinese.

Content is organized by directory:

content/docs/en/...
content/docs/zh/...

English is the source of truth and fallback language. If a Chinese page is missing, Fumadocs falls back to the English source.

Generated README references intentionally exist only under content/docs/en. Do not hand-edit or translate generated readme-*.mdx files.

Adding Pages

1. Add the English .mdx file under content/docs/en/.
2. Add the Chinese .mdx file under content/docs/zh/ when the page is intended for human Chinese readers.
3. Add or update the nearest meta.json pages list to control sidebar order.
4. Prefer paths and command examples that match the current repository state.
5. Export UNIRL_SOURCE_ROOT, then run npm run docs:check, npm run typecheck, and npm run build before submitting changes.

Maintenance Notes

• Node >=20.19.0 is declared because current transitive file-watcher dependencies require it. Older Node versions may still build but will warn during install.
• includeProcessedMarkdown is enabled in source.config.ts; do not remove it unless /llms-full.txt and /md/<slug>/index.md are replaced with another Markdown source.
• Generated directories .next/, .source/, out/, and node_modules/ are ignored by the repository.
• Generated package pages content/docs/en/<section>/readme-*.mdx come from npm run sync:readmes and are git-ignored; edit the source README, not these files.