diff --git a/docs/README.md b/docs/README.md index 3f1c2036e..fa27ae704 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,74 +1,109 @@ # OpenUI Docs -Documentation site for the OpenUI SDK, built with [Next.js 16](https://nextjs.org) + [Fumadocs](https://fumadocs.dev) + the OpenUI Design System. +Documentation site for the OpenUI SDK, built with [Next.js](https://nextjs.org) + [Fumadocs](https://fumadocs.dev) + the OpenUI Design System. ## Setup -This project lives at `js/packages/docs-v3` inside the pnpm workspace, with a symlink at `repo/docs-v3` for convenience. It links `@openuidev/react-core` and `@openuidev/react-ui` from the monorepo via `workspace:^`. +This project lives at `docs` inside the pnpm workspace. It links `@openuidev/lang-core`, `@openuidev/react-lang`, `@openuidev/react-headless`, `@openuidev/react-ui`, and `@openuidev/cli` from the monorepo via `workspace:*` / `workspace:^`. ```bash # Install from workspace root -cd js && pnpm install +pnpm install -# Dev/build from docs-v3 (either path works) -cd js/packages/docs-v3 # or cd docs-v3 (symlink) -pnpm dev -pnpm build +# Start the documentation development server +pnpm --filter @openuidev/docs dev + +# Build the documentation site for production +pnpm --filter @openuidev/docs build ``` ## Project structure ``` -docs-v3/ +docs/ ├── app/ │ ├── layout.tsx # Root layout (html, body, fonts, providers) │ ├── global.css # Global styles + design-system CSS imports +│ ├── providers.tsx # App-level providers +│ ├── robots.ts # Robots.txt generation +│ ├── sitemap.ts # Sitemap generation │ │ │ ├── (home)/ # Landing page (no docs layout) -│ │ ├── layout.tsx # DocsNavbar + content wrapper +│ │ ├── layout.tsx # Web theme provider + home Navbar │ │ └── page.tsx │ │ │ ├── docs/ # Fumadocs documentation pages │ │ ├── layout.tsx # DocsLayout (sidebar, nav) │ │ └── [[...slug]]/page.tsx # Catch-all rendering MDX from content/docs/ │ │ -│ ├── (design-system)/ # Route group — bypasses Fumadocs layout -│ │ └── docs/design-system/ # Serves /docs/design-system/* -│ │ ├── layout.tsx # AppThemeProvider + DS TopNav shell -│ │ ├── page.tsx # Redirects → /docs/design-system/foundation/colors -│ │ ├── blocks/ # Component block previews -│ │ ├── foundation/ # Design tokens (colors, spacing, etc.) -│ │ └── compose/ # Composition examples +│ ├── components/ # Component / Design System pages +│ │ ├── layout.tsx # AppThemeProvider + TopNav shell +│ │ ├── page.tsx # Design System landing page +│ │ ├── blocks/ # Component block previews +│ │ ├── foundation/ # Design tokens (colors, spacing, etc.) +│ │ ├── compose/ # Composition examples +│ │ ├── customize/ # Component customizer +│ │ └── theme-builder/ # Theme creator interface +│ │ +│ ├── blog/ # Blog pages +│ ├── demo/ # Demo route +│ ├── playground/ # Interactive playground │ │ -│ ├── api/search/route.ts # Search endpoint +│ ├── api/ # API routes +│ │ ├── search/ # Search endpoint +│ │ ├── chat/ # Chat API +│ │ ├── demo/ # Demo API +│ │ └── playground/ # Playground API │ ├── og/docs/[...slug]/route.tsx # OG image generation │ └── llms.txt/, llms-full.txt/, llms.mdx/ # LLM-friendly content endpoints │ ├── components/ # Docs-site components │ ├── docs-navbar.tsx # Top navbar (section tabs, search, GitHub) -│ └── ai/page-actions.tsx # Copy/open actions on doc pages +│ ├── brand-logo.tsx # Brand logo + GitHub star button +│ ├── theme-toggle.tsx # Dark/light mode toggle +│ ├── ai/ # AI-powered page actions +│ └── ... # Site headers, marketing components, etc. │ -├── content/docs/ # MDX content (Fumadocs source) -│ ├── meta.json # Root sidebar config -│ ├── introduction/ # Getting started guides -│ ├── generative-ui/ # GenUI docs -│ ├── chat/ # Chat SDK docs -│ └── api-reference/ # API reference +├── content/ +│ ├── docs/ # MDX content (Fumadocs source) +│ │ ├── meta.json # Root sidebar config +│ │ ├── openui-lang/ # OpenUI Core language docs +│ │ ├── chat/ # Chat SDK docs +│ │ ├── api-reference/ # API reference +│ │ └── mcp/ # MCP docs +│ └── blog/ # Blog MDX content │ -├── shared/design-system/ # Design system shared code (non-route) -│ ├── components/ # UI components (SideNav, TopNav, preview/, etc.) -│ ├── config/ # Navigation config, compose example data -│ ├── styles/ # CSS custom properties (colors, spacing, typography) -│ └── types/ # TypeScript types +├── generated/ # Autogenerated prompt & spec outputs +│ ├── chat-system-prompt.txt +│ ├── playground-component-spec.json +│ └── playground-system-prompt.txt +│ +├── shared/ # Shared code and style tokens +│ ├── design-system/ # Legacy design system code (unused by active components) +│ │ ├── components/ # UI components (SideNav, TopNav, preview/, etc.) +│ │ ├── config/ # Navigation config, compose example data +│ │ ├── styles/ # CSS custom properties (colors, spacing, typography) +│ │ └── types/ # TypeScript types +│ └── theme/ # Application theme styling │ ├── lib/ # Utilities │ ├── source.ts # Fumadocs source config │ ├── layout.shared.tsx # Shared layout options -│ └── cn.ts # className merge utility +│ ├── cn.ts # className merge utility +│ ├── chat-library.ts # Chat library config +│ ├── demo-credits.ts # Demo credits data +│ └── playground-library.ts # Playground library config +│ +├── imports/ # Shared imported assets/components +├── types/ # TypeScript type declarations +├── public/ # Static assets │ ├── next.config.mjs # Redirects, rewrites, turbopack root -├── tsconfig.json # Path aliases: @/*, @design-system/* +├── tsconfig.json # Path aliases: @/*, @components/*, @design-system/* ├── source.config.ts # Fumadocs MDX collection config +├── postcss.config.mjs # PostCSS config +├── eslint.config.mjs # ESLint config +├── mdx-components.tsx # MDX component overrides └── package.json ``` @@ -78,28 +113,29 @@ docs-v3/ MDX files in `content/docs/` are rendered by the catch-all route at `app/docs/[[...slug]]/page.tsx`. Fumadocs handles sidebar generation from `meta.json` files, search indexing, and page layout. -Each top-level section (`introduction`, `generative-ui`, `chat`, `api-reference`) has `"root": true` in its `meta.json`, which gives it an isolated sidebar. +Each section maintains its own navigation structure through its `meta.json` configuration. ### Design System pages -The design system lives at `/docs/design-system/*` and uses a **route group** `(design-system)` to avoid inheriting the Fumadocs `DocsLayout` (which would add the Fumadocs sidebar). It has its own layout with `AppThemeProvider`, a `TopNav` (Blocks / Foundation / Compose), and section-specific `SideNav` components. +The design system lives at `/components/*` and serves component previews (Blocks / Foundation / Compose) with its own theme provider and navigation under `app/components/`. -Shared code is in `shared/design-system/` and imported via the `@design-system/*` path alias. +Active component-preview specific modules are located under `app/components/` and imported via the `@components/*` path alias. The `shared/design-system/` folder contains legacy implementation code that is not used by active component pages. ### Navigation -A custom `DocsNavbar` component (`components/docs-navbar.tsx`) provides top-level horizontal tabs: Introduction, Generative UI, Design System, Chat, API Reference. It replaces Fumadocs' default nav and is shared between the homepage and docs layouts. +A custom `DocsNavbar` component (`components/docs-navbar.tsx`) provides top-level horizontal tabs: OpenUI, Chat, API Reference. It replaces Fumadocs' default nav and is used across the docs pages. ## Path aliases -| Alias | Resolves to | Usage | -| ------------------ | -------------------------- | ------------------------------------------ | -| `@/*` | `./` (project root) | Docs-site code (`@/components/`, `@/lib/`) | -| `@design-system/*` | `./shared/design-system/*` | Design system shared code | +| Alias | Resolves to | Usage | +| ------------------ | -------------------------- | ----------------------------------------------- | +| `@/*` | `./` (project root) | Docs-site code (`@/components/`, `@/lib/`) | +| `@components/*` | `./app/components/*` | Component preview sub-app specific modules | +| `@design-system/*` | `./shared/design-system/*` | Legacy path alias (unused by active components) | ## Key dependencies -- **`@openuidev/react-core`**, **`@openuidev/react-ui`** — Linked from the monorepo via `workspace:^`. Provides `ThemeProvider`, chart components, and UI primitives used by the design system. +- **`@openuidev/lang-core`**, **`@openuidev/react-lang`**, **`@openuidev/react-headless`**, **`@openuidev/react-ui`**, and **`@openuidev/cli`** — Linked from the monorepo via `workspace:*` / `workspace:^`. Provide core schemas, component libraries, UI controls, hooks, and builders. - **`fumadocs-core` / `fumadocs-ui` / `fumadocs-mdx`** — Documentation framework. - **`prism-react-renderer`** — Syntax highlighting in design system code blocks. @@ -111,6 +147,6 @@ A custom `DocsNavbar` component (`components/docs-navbar.tsx`) provides top-leve ## Adding design system pages -1. Add the route page in `app/(design-system)/docs/design-system/
/`. -2. Add shared components/config in `shared/design-system/`. -3. Update `shared/design-system/config/navigation.ts` with the new nav items. +1. Add the route page in `app/components/
/`. +2. Add shared components/config inside `app/components/` (imported via the `@components/*` path alias). +3. Update `app/components/config/navigation.ts` with the new nav items.