Configuration

Clearify works with zero configuration. But when you need control, create a clearify.config.ts:

import { defineConfig } from '@marlinjai/clearify';

export default defineConfig({
  name: 'My Project',
  theme: {
    primaryColor: '#8B5CF6',
    mode: 'auto',
  },
});

Options

Mermaid Diagrams

By default, Mermaid diagrams render client-side using the full Mermaid JS library (~2.1MB). For production sites, you can switch to build-time rendering which pre-renders diagrams to SVGs via Puppeteer and eliminates all Mermaid JS from the client bundle:

export default defineConfig({
  mermaid: {
    strategy: 'build',
  },
});

Requires Puppeteer as a dev dependency:

npm install puppeteer

Sections

For multi-section docs (e.g. public + internal), use the sections array instead of docsDir:

import { defineConfig } from '@marlinjai/clearify';

export default defineConfig({
  name: 'My Project',
  sections: [
    { label: 'Docs', docsDir: './docs/public' },
    { label: 'Internal', docsDir: './docs/internal', basePath: '/internal', draft: true },
  ],
});

Section options

SEO

Set siteUrl to enable canonical URLs, Open Graph tags, and sitemap generation in production builds:

export default defineConfig({
  name: 'My Project',
  siteUrl: 'https://docs.example.com',
});

The build generates:

• Per-page <title>, <meta description>, <link rel="canonical">
• Open Graph and Twitter Card meta tags
• JSON-LD structured data (Article schema)
• sitemap.xml (respects section sitemap option)
• robots.txt with sitemap reference

Hub Mode

Hub Mode turns a Clearify site into a project dashboard — ideal for monorepos or multi-project portfolios. It renders a grid of project cards with status badges, descriptions, and links.

Manual project list

List projects explicitly in hub.projects:

export default defineConfig({
  name: 'ERP Suite',
  hub: {
    projects: [
      {
        name: 'Storage Brain',
        description: 'File storage & processing service',
        href: 'https://storage-brain.example.com',
        status: 'active',
        icon: '🧠',
        tags: ['cloudflare', 'r2'],
      },
      {
        name: 'Data Table',
        description: 'Notion-like database component',
        status: 'beta',
        tags: ['react', 'component'],
      },
    ],
  },
});

Auto-scan (hub.scan)

Instead of listing every project manually, point hub.scan at child config files. Each child declares a hubProject block and the hub assembles the grid automatically:

Parent config (hub site):

export default defineConfig({
  name: 'ERP Suite',
  hub: {
    scan: './projects/*/clearify.config.ts',
  },
});

Child config (e.g. projects/storage-brain/clearify.config.ts):

export default defineConfig({
  name: 'Storage Brain',
  siteUrl: 'https://storage-brain.example.com',
  hubProject: {
    description: 'File storage & processing service',
    status: 'active',
    icon: '🧠',
    tags: ['cloudflare', 'r2'],
  },
});

The scanner uses name from the child config and href from hubProject.href (falling back to siteUrl). Manual hub.projects entries override scanned ones by name.

Hub config options

HubProject fields

Hub components

Hub Mode ships three components that render automatically from the virtual:clearify/hub module:

• ProjectGrid — responsive grid layout (3 columns, collapses to 2 → 1 on smaller screens)
• ProjectCard — card with name, description, status badge, tags, and optional GitHub link
• StatusBadge — color-coded status pill (active green, beta indigo, planned amber, deprecated red)