Set up and manage Synapse documentation projects. Handles npm-based project initialization, schema cascade configuration, mode detection, versioning, and CI/CD publishing.
Set up, configure, and manage Synapse documentation projects. Covers the full lifecycle from project initialization to npm publishing.
mkdir my-docs && cd my-docs
npm init -y
npm install @millstone/synapse-cli
# Create content directories
npx synapse scaffold --type meeting --title "Kickoff Meeting"
# Validate
npx synapse validate
The resulting package.json:
{
"private": true,
"type": "module",
"scripts": {
"validate": "synapse validate",
"scaffold": "synapse scaffold"
},
"dependencies": {
"@millstone/synapse-cli": "^2.0.0"
}
}
The CLI resolves schemas in priority order:
schemas/frontmatter/custom/*.json, schemas/body-grammars/custom/*.jsonschemas/frontmatter/*.json, schemas/body-grammars/*.jsonnode_modules/@millstone/synapse-schemas/To override a base schema (e.g., add a custom document type):
mkdir -p schemas/frontmatter/custom
Create schemas/frontmatter/custom/my-type.frontmatter.schema.json:
{
"$id": "my-type.frontmatter",
"type": "object",
"properties": {
"type": { "const": "my-type" },
"title": { "type": "string" }
},
"required": ["type", "title"]
}
Custom schemas take priority over base schemas with the same filename.
Create schemas/body-grammars/custom/my-type.body-grammar.json:
{
"type": "my-type",
"displayName": "My Custom Type",
"sections": [
{
"id": "overview",
"title": "Overview",
"required": true,
"order": 1,
"shape": {
"type": "flow",
"allowedNodes": ["paragraph", "list", "heading"]
}
}
]
}
The Synapse monorepo contains four publishable packages:
packages/
cli/ → @millstone/synapse-cli (main CLI tool)
schemas/ → @millstone/synapse-schemas (frontmatter + body-grammar schemas)
context-mcp/ → @millstone/synapse-context-mcp (MCP server for context)
site/ → @millstone/synapse-site (static site generator)
All packages use lock-step versioning — same version number across all four.
./scripts/bump-version.sh <new-version>
Updates version in all four package.json files plus root.
The GitHub Actions workflow (.github/workflows/publish.yml) publishes packages in dependency order:
@millstone/synapse-schemas (no deps)@millstone/synapse-cli (depends on schemas)@millstone/synapse-context-mcp@millstone/synapse-siteTriggered by version tags (v*.*.*) or manual workflow_dispatch with dry-run option.
{
"branding": {
"siteName": "My Documentation",
"displayName": "My Documentation",
"baseUrl": "https://docs.example.com"
},
"schemas": {
"customDir": "schemas/custom",
"loadBase": true
}
}
The schemas package isn't installed. Run npm install or check that @millstone/synapse-cli is in your dependencies.
Ensure CI runs npm install before synapse validate. The schemas package must be installed.
Check file location: must be in schemas/frontmatter/custom/ or schemas/body-grammars/custom/. The filename must match the pattern <type>.frontmatter.schema.json or <type>.body-grammar.json.