LocusGraph Builder Documentation

This directory contains the Vocs-based documentation site for LocusGraph.

Tech Stack

• Vocs for docs site generation
• React + MDX for page authoring
• TypeScript for config and custom components

Project Structure

docs/
├── vocs.config.ts         # Site config (sidebar, top nav, socials, theme)
├── package.json           # Scripts and dependencies
├── pnpm-lock.yaml         # Lockfile
├── layout.tsx             # Root layout wrapper
├── styles.css             # Global styles + theme tokens
├── components/            # Reusable MDX/React UI components
│   ├── api-endpoint.tsx
│   ├── badge.tsx
│   ├── Callout.tsx
│   ├── code-group.tsx
│   ├── link-card.tsx
│   ├── param-table.tsx
│   ├── response-preview.tsx
│   ├── step.tsx
│   ├── table.tsx
│   └── tabs.tsx
└── pages/                 # Documentation routes
    ├── index.tsx          # Root page (currently redirects to introduction)
    ├── getting-started/
    ├── concepts/
    ├── mcp/
    ├── context-engineering/
    ├── workflows/
    ├── sdks/
    ├── integrations/
    ├── api/
    ├── guides/
    └── support/

Local Development

Install dependencies:

pnpm install

Run the docs dev server:

pnpm dev

Build for production:

pnpm build

Preview the production build:

pnpm preview

How Navigation Works

• Sidebar groups and links are defined in vocs.config.ts under sidebar.
• Top navigation links are defined in vocs.config.ts under topNav.
• Social links are defined in vocs.config.ts under socials.
• Theme colors/tokens are configured in vocs.config.ts and refined in styles.css.

Adding or Updating Pages

1. Create or edit a page in pages/ using .mdx (or .tsx where needed).
2. Add/update the matching route in vocs.config.ts so it appears in the sidebar.
3. Import reusable UI blocks from components/ when needed.

Example page skeleton:

# Page Title

Brief intro for the page.

Contributor Workflow

Use this lightweight workflow for docs changes:

1. Sync your branch with the latest main branch.
2. Create a focused branch (example: docs/update-mcp-clients-page).
3. Run pnpm dev and keep the preview open while editing.
4. Make page/config/component changes.
5. Verify navigation, links, and code snippets locally.
6. Run pnpm build before opening a PR.
7. Open a PR with:
   • What changed
   • Why it changed
   • Any screenshots (if visual/layout changes)
   • Quick test notes

Recommended branch naming:

• docs/<topic>
• docs/fix-<issue>
• docs/update-<section>

Editing Guide

1) Content Edits (Most Common)

• Edit .mdx files under pages/.
• Keep one clear H1 (#) at the top.
• Prefer short sections, descriptive headings, and practical examples.
• Use inline code formatting for commands, env vars, and identifiers.

2) Navigation and IA Edits

• Update vocs.config.ts:
  • sidebar for left navigation groups/pages
  • topNav for top-level links
  • socials for icon links
• Ensure every sidebar link points to an existing route in pages/.

3) Reusable Component Usage

• Import shared components from components/ in MDX pages.
• Existing common blocks:
  • Callout for notes/warnings/tips
  • CodeGroup for language tabs
  • Step/Steps for guided flows
  • LinkCard for "next step" navigation
  • ApiEndpoint, ParamTable, ResponsePreview for API docs

4) Layout and Styling Edits

• Global wrapper: layout.tsx
• Global theme/styles: styles.css
• Site-level tokens/config: vocs.config.ts
• Keep style changes consistent with existing design tokens and spacing scale.

5) Quality Checklist Before PR

• pnpm dev runs without issues.
• pnpm build succeeds.
• New/updated pages appear in sidebar as expected.
• Internal links work (no broken links in edited sections).
• Code snippets are copy-pasteable and use current SDK/API names.
• Wording is consistent (LocusGraph terminology, capitalization, tone).

Notes

• pages/index.tsx currently redirects / to /getting-started/introduction.
• layout.tsx currently provides a minimal root wrapper and imports global styles.

Deploy to Vercel

1. Push this repository to GitHub.
2. Import the repository in Vercel.
3. Ensure Vercel project settings use:
   • Install Command: pnpm install
   • Build Command: pnpm build
   • Node.js Version: 20.x
4. Deploy and keep auto-deploy enabled for your main branch.