# Documentation Site & Live Examples

> The Next.js app (apps/docs) that serves the public faces of diffs.com and trees.software: route groups for multiple brands, MDX-driven documentation, live component previews, a build pipeline that rebuilds the three published packages on every dev start, llms.txt generation, and E2E tests that exercise the real rendered output. Also contains the small Vite demo app.

- Repository: pierrecomputer/pierre
- GitHub: https://github.com/pierrecomputer/pierre
- Human wiki: https://grok-wiki.com/public/wiki/pierrecomputer-pierre-fac2c554b845
- Complete Markdown: https://grok-wiki.com/public/wiki/pierrecomputer-pierre-fac2c554b845/llms-full.txt

## Source Files

- `apps/docs/package.json`
- `apps/docs/app/layout.tsx`
- `apps/docs/app/page.tsx`
- `apps/docs/scripts/generate-llms-txt.ts`
- `apps/docs/lib/mdx.tsx`
- `apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/content.mdx`
- `apps/demo/src/main.ts`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:

- [apps/docs/package.json](apps/docs/package.json)
- [apps/docs/app/layout.tsx](apps/docs/app/layout.tsx)
- [apps/docs/app/page.tsx](apps/docs/app/page.tsx)
- [apps/docs/scripts/generate-llms-txt.ts](apps/docs/scripts/generate-llms-txt.ts)
- [apps/docs/lib/mdx.tsx](apps/docs/lib/mdx.tsx)
- [apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/content.mdx](apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/content.mdx)
- [apps/demo/src/main.ts](apps/demo/src/main.ts)
- [apps/docs/lib/product-config.ts](apps/docs/lib/product-config.ts)
- [apps/docs/next.config.mjs](apps/docs/next.config.mjs)
- [apps/docs/components/docs/DocsCodeExample.tsx](apps/docs/components/docs/DocsCodeExample.tsx)
- [apps/docs/components/docs/DocsLayout.tsx](apps/docs/components/docs/DocsLayout.tsx)
- [apps/docs/test/e2e/playwright.config.ts](apps/docs/test/e2e/playwright.config.ts)
- [apps/docs/app/(trees)/_docs/DocsPage.tsx](apps/docs/app/(trees)/_docs/DocsPage.tsx)
- [apps/docs/app/docs/page.tsx](apps/docs/app/docs/page.tsx)
- [apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/constants.ts](apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/constants.ts)
- [apps/docs/components/docs/DocsSidebar.tsx](apps/docs/components/docs/DocsSidebar.tsx)
</details>

# Documentation Site & Live Examples

The `apps/docs` Next.js application is the public delivery layer for the three Pierre product sites: diffs.com, trees.software, and the diffshub.com microsite. It uses build-time environment selection (`NEXT_PUBLIC_SITE`) and Next.js route groups to serve completely separate branded experiences from a single codebase while sharing documentation infrastructure, component libraries, and the published packages themselves.

Documentation is authored in MDX, rendered server-side, and enhanced with live, interactive previews of the actual `@pierre/diffs` and `@pierre/trees` components. A dedicated build step ensures the three published packages are always rebuilt from source before the docs server starts. The same pipeline also emits `llms.txt` and `llms-full.txt` files for AI consumption. End-to-end Playwright tests run against the fully built production output.

A small companion Vite application (`apps/demo`) demonstrates the packages in a minimal vanilla + React context outside the docs site.

## Multi-Brand Routing Architecture

Route groups under `app/(diffs)`, `app/(trees)`, and `app/(diffshub)` isolate brand-specific pages, layouts, and assets. The root `app/page.tsx` and `app/docs/page.tsx` act as static dispatchers:

```tsx
// apps/docs/app/page.tsx:10-13
const SITE = process.env.NEXT_PUBLIC_SITE;
const Page = SITE === 'trees' ? TreesHome : SITE === 'diffshub' ? DiffshubHome : DiffsHome;
export default Page;
```

`app/layout.tsx` reads the same variable to select per-site metadata, favicons, Open Graph images, viewport behavior, and theme bootstrap. Worktree-aware title prefixes are injected for parallel development.

Redirects in `next.config.mjs` keep legacy paths working while pointing cross-product traffic to the correct domain.

**Sources:** [apps/docs/app/page.tsx:1-14](), [apps/docs/app/layout.tsx:45-140](), [apps/docs/app/docs/page.tsx:1-20](), [apps/docs/next.config.mjs:60-95]()

## MDX-Driven Documentation Content

Each documentation section lives in a folder containing `content.mdx` and an optional `constants.ts`. The `renderMDX` and `renderMDXWithPreloadedFiles` helpers in `lib/mdx.tsx` compile the MDX at request time inside React Server Components.

```tsx
// apps/docs/lib/mdx.tsx:45-70
export async function renderMDX({ filePath, scope = {} }: RenderMDXOptions) {
  const fullPath = join(process.cwd(), 'app', filePath);
  const source = await readFile(fullPath, 'utf-8');
  const { content } = await compileMDX({ source, components: defaultComponents, ... });
  return content;
}
```

Remark and rehype plugins add GitHub-flavored markdown, table-of-contents slugging, and `[toc-ignore]` support. Custom components (`Notice`, `DocsCodeExample`, tab switchers, live `<MultiFileDiff>` instances, etc.) are registered once and available in every MDX file.

Trees documentation contains 18 sections; diffs documentation contains 14 sections. Both are organized under `Guides/` and `Reference/` with consistent front-matter-free heading extraction used for navigation and llms.txt anchors.

**Sources:** [apps/docs/lib/mdx.tsx:1-95](), [apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/content.mdx:1-70](), [apps/docs/app/(trees)/_docs/DocsPage.tsx:20-80]()

## Live Component Previews

The `DocsCodeExample` component renders real instances of the published packages directly inside the documentation:

```tsx
// apps/docs/components/docs/DocsCodeExample.tsx:20-35
export function DocsCodeExample<LAnnotation = undefined>(props: DocsCodeExampleProps<LAnnotation>) {
  return (
    <File {...rest} className="..." renderHeaderMetadata={(file) => (...)} />
  );
}
```

Authors export `PreloadFileOptions` objects (or tree equivalents) from a sibling `constants.ts`. `renderMDXWithPreloadedFiles` calls `preloadFile` (from `@pierre/diffs/ssr`) in parallel at build/render time and injects the results into MDX scope so the live component receives pre-highlighted, production-grade data.

This pattern guarantees that every code sample shown to readers is also a working, interactive demo of the exact code the reader will copy.

**Sources:** [apps/docs/components/docs/DocsCodeExample.tsx:1-45](), [apps/docs/app/(trees)/docs/Guides/GetStartedWithReact/constants.ts:1-30](), [apps/docs/lib/mdx.tsx:75-95]()

## Package Rebuild Pipeline

The docs `package.json` scripts guarantee fresh builds of the workspace packages on every developer start:

```json
// apps/docs/package.json:6-20
"build:deps": "bun run build:deps:diffs && bun run build:deps:truncate && bun run build:deps:tree",
"build:deps:diffs": "output=$(cd ../../packages/diffs && bun run build 2>&1) ...",
"_dev": "bun run build:deps && bun concurrently \"bun run dev:deps:diffs\" ... \"bun run dev:next\" ..."
```

`diffs:dev`, `trees:dev`, and `diffshub:dev` each set `NEXT_PUBLIC_SITE` and a port offset, then invoke the shared `_dev` target. The same `build:deps` step runs before `next build`, before E2E tests, and before the Vite demo. This eliminates the class of "stale package" bugs that would otherwise appear when editing the core libraries while viewing their documentation.

**Sources:** [apps/docs/package.json:1-45](), [apps/demo/package.json:8-15]()

## llms.txt Generation

`scripts/generate-llms-txt.ts` runs as part of the production build. It:

1. Reads every `content.mdx` for the active product (`diffs` or `trees`).
2. Strips JSX and converts `<Notice>` elements to blockquotes.
3. Auto-discovers code examples from exported constants in sibling `constants.ts` files.
4. Assembles a compact `llms.txt` (section index) and a full `llms-full.txt` (entire prose + examples).

Output always lands at `public/llms.txt` and `public/llms-full.txt` so the files are served at the root of whichever domain the current build targets. Diffshub builds skip generation cleanly.

**Sources:** [apps/docs/scripts/generate-llms-txt.ts:140-200](), [apps/docs/scripts/generate-llms-txt.ts:260-320](), [apps/docs/package.json:8]()

## E2E Tests That Exercise Real Rendered Output

Playwright configuration (`test/e2e/playwright.config.ts`) starts the production server (`bun run start`) after a full `build:deps && build:next`. Tests run in a real browser against the exact HTML, CSS, and JavaScript that end users receive. Current coverage focuses on high-risk interactive surfaces (context menus, drag-and-drop, item customization) inside the trees development playground.

The web server command and port-offset handling mirror the worktree-aware dev scripts, so tests remain stable across parallel worktrees.

**Sources:** [apps/docs/test/e2e/playwright.config.ts:1-45](), [apps/docs/package.json:30-35]()

## The Small Vite Demo App

`apps/demo` is a minimal Vite + React application that consumes `@pierre/diffs` (and transitively the other packages) directly. Its `main.ts` wires up `File`, `FileDiff`, `VirtualizedFileDiff`, `FileStream`, worker pools, and annotation renderers with the same patterns used in the docs examples and the diffshub microsite.

It serves as both a manual testing surface for the packages and a living reference for consumers who prefer a non-Next.js environment. Like the docs app, it runs `build:deps` before Vite starts.

**Sources:** [apps/demo/src/main.ts:1-50](), [apps/demo/package.json:1-25](), [apps/demo/vite.config.ts]()

## Summary

`apps/docs` is not a passive documentation host. It is an active integration surface that forces the published packages to stay buildable, renders them live inside their own reference material, emits AI-friendly text artifacts, and validates the final output with browser tests. The combination of route-group isolation, MDX + preload scope, the `build:deps` contract, and the `DocsCodeExample` pattern gives contributors a single place to author, demonstrate, and ship changes across all public Pierre products.

**Sources:** [apps/docs/package.json:6-45](), [apps/docs/lib/mdx.tsx:75-95](), [apps/docs/scripts/generate-llms-txt.ts:1-50]()