Skip to content

docs: update stale contributor setup and architecture in docs/README.md #650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shogun444 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: update stale contributor setup and architecture in docs/README.md #650

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4fd1135
docs: update stale contributor setup and architecture in docs/README.md
shogun444 Jun 13, 2026
4764461
docs: address PR review feedback for README
shogun444 Jun 15, 2026
2ad9a98
Merge branch 'upstream/main' into docs-update-readme-636
shogun444 Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 79 additions & 43 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```

Expand All @@ -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.

Expand All @@ -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/<section>/`.
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/<section>/`.
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.
Loading