Appearance

CLAUDE.md ​

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview ​

Junto Docs is the documentation site for the Junto AI Helpdesk platform (an MSP-focused SaaS product). Built with VitePress, deployed on Netlify at docs.juntoai.com.

Commands ​

  • npm run dev — Start dev server with hot reload (localhost:5173)
  • npm run build — Build search index + VitePress static site (output: .vitepress/dist/)
  • npm run preview — Preview production build locally
  • docker-compose up — Alternative dev server via Docker (localhost:5175)

There are no linting or test commands — this is a content-only documentation site.

Architecture ​

VitePress 1.6.3 static site generator (Vite + Vue). Node 20.

Key Files ​

  • .vitepress/config.ts — Central config: nav bar, sidebar structure, SEO meta tags, PostHog analytics snippet, sitemap. Every new page must be added to the sidebar here or it won't appear in navigation.
  • .vitepress/theme/index.ts — Extends default VitePress theme, imports custom CSS.
  • .vitepress/theme/custom.css — Brand colors (purple #3E1F47 light / #a06bb5 dark) via CSS custom properties.
  • scripts/build-search-index.mjs — Pre-build script that crawls all .md files, strips markdown, and generates netlify/functions/search-index.json. Runs automatically as part of npm run build.
  • netlify.toml — Build config, security headers (CSP, X-Frame-Options), cache rules, and /api/search redirect to Netlify Functions.

Content Structure ​

All content is Markdown with YAML frontmatter (title and description are required on every page):

getting-started/   — Onboarding (What is Junto, AI Agent, General Assistant)
integrations/      — ~25 integration setup guides (ConnectWise, NinjaOne, ITGlue, etc.)
general/           — Features (Advisor, Ticket Health, etc.) and Runbooks
settings/          — AI Processor documentation (~12 processors)
faqs/              — FAQ pages by category

The sidebar in config.ts groups these into 6 sections: Getting Started, Integrations, Runbooks, Features, Processors, FAQs.

Adding a New Page ​

  1. Create the .md file in the appropriate directory with title and description frontmatter.
  2. Add the page to the sidebar array in .vitepress/config.ts under the correct section.
  3. The search index is regenerated automatically on npm run build.

Content Conventions ​

  • Integration guides follow a consistent pattern: Prerequisites, Setup steps, Configuration tables, Feature details.
  • Processor docs (settings/processor-*.md) each explain: what it does, when to use it, configuration options.
  • URLs are clean (no .html extension) — configured via cleanUrls: true.
  • index.md files serve as section landing pages.

Deployment ​

Netlify auto-deploys on push to main. No CI/CD workflows beyond Netlify's built-in pipeline.