synapse-docs

Synapse Documentation Framework

Obsidian-first, Git-native documentation framework with reusable templates, realistic examples, strict validation, and self-hosted static publishing and CMS.

Features

• Obsidian-compatible Markdown with YAML Properties
• Templates for Policies, Standards, Processes, SOPs, Runbooks, Systems, ADRs, PRDs, Capabilities, and TDDs
• Strict validation (schemas, cross-links, naming/placement)
• Quartz 4 static site (graph, backlinks, tags)
• Decap CMS (self-hosted) for non-technical editing
• Formatting and validation commands

Quick Start

Prerequisites

• Node 20+
• Git

Option A: npm install (recommended)

# Scaffold a new Synapse documentation project
npx @millstone/synapse-cli scaffold --type adr --title "My First ADR"

# Or set up a full project with package.json
npm init -y
npm install @millstone/synapse-cli

# Create documents
npx synapse scaffold --type policy --title "Security Policy" --owner "Security Team"
npx synapse scaffold --type sop --title "Deployment Procedure"

# Validate and format
npx synapse validate
npx synapse format --write

Daily Usage

1. Create documents: Use synapse scaffold to create new documents from templates

npx synapse scaffold --type adr --title "Use React for Frontend"

2. Validate: Run before committing

npx synapse validate

3. Format: Auto-format document body sections

npx synapse format --write

Pro Tips

1. Run validation before committing: npx synapse validate catches schema, naming, and cross-link errors
2. Use strict mode: Enabled by default; use --no-strict to allow filename/title mismatches
3. Check examples: Look in content/*/examples/ for valid document samples
4. Format automatically: npx synapse format --write fixes body section structure

Packages

This monorepo contains the following packages:

Package	Description
@millstone/synapse-cli	CLI for validation, formatting, scaffolding, and PDF generation
@millstone/synapse-schemas	JSON Schema definitions for frontmatter, body grammars, and plugins
@millstone/synapse-site	Quartz 4 static site generator configuration
@millstone/synapse-context-mcp	MCP server for AI-assisted documentation

Configuration

Synapse uses synapse.config.json at the repository root for project customization.

Folder Structure Override

By default, documents are organized in predefined folders:

• Policies -> content/10_Policies
• Systems -> content/70_Systems
• ADRs -> content/90_Architecture/ADRs
• etc.

You can customize folder locations:

{
  "folders": {
    "system": "75_Systems",
    "policy": "15_Policies"
  }
}

The CLI validation automatically adapts to custom folder locations. Unmapped types continue using their default folders.

Branding Configuration

{
  "branding": {
    "siteName": "My Company Docs",
    "displayName": "My Company Documentation",
    "baseUrl": "https://docs.example.com",
    "logo": "tools/pdf/logo.png",
    "theme": {
      "lightMode": { "primary": "#1976d2" },
      "darkMode": { "primary": "#90caf9" }
    }
  }
}

Decap CMS Backend

{
  "decap": {
    "enabled": true,
    "backend": "github",
    "repo": "org/repo",
    "oauthProxy": "https://oauth.example.com"
  }
}

Schema Resolution

The CLI resolves schemas using a cascade:

1. Local override: {projectRoot}/schemas/frontmatter/*.schema.json -- for project-specific customizations
2. @millstone/synapse-schemas package: Installed via npm -- the standard schema set
3. Error: With a helpful message explaining how to fix

This allows projects to override individual schemas while falling back to the standard set. The same cascade applies to body grammar rules.

{
  "schemas": {
    "customDir": "schemas/custom",
    "loadBase": true
  }
}

Decap CMS (Self-hosted)

• Serves under /admin
• Configure backend for your Git provider (GitHub/GitLab/Gitea)
• Use an OAuth proxy to exchange auth codes for tokens
• Collections mirror type folders; fields map to schema fields
• Field-level "required" and "pattern" constraints provide early feedback

Quartz 4 Site

• contentDir: ./content
• Graph, backlinks, tags enabled
• Publish via CI to internal static hosting

Testing

The Synapse CLI includes a comprehensive test suite using Jest with TypeScript support. Tests ensure code quality, prevent regressions, and maintain coverage above 80%.

Running Tests

# Run all tests with coverage
npm test

# Generate detailed coverage report
npm run coverage:report

Coverage Requirements

The project enforces minimum coverage thresholds of 80% for statements, branches, functions, and lines.