Docs Components - Ensemble Edge

Define and version reusable documentation as components with Handlebars template support for dynamic content.

Overview

Docs components enable you to:

Reuse documentation across multiple projects and contexts
Version docs with semantic versioning for consistency
Dynamic content using Handlebars variables and helpers
A/B test different documentation versions
Deploy documentation independently from code
Auto-discover markdown files at build time

Quick Start

1. Create a Docs Component

Create a markdown file with optional Handlebars variables:

// docs/getting-started.md
---
title: Getting Started
description: Quick start guide
---

# Welcome to {{projectName}}

Version: {{version}}

Get started with {{projectName}} in just a few minutes.

## Prerequisites

- Node.js {{nodeVersion}} or higher
- npm or yarn

## Installation

\`\`\`bash
npm install {{projectName}}
\`\`\`

## Your First Request

{{#if hasApiKey}}
Use your API key to make authenticated requests:

\`\`\`javascript
const client = new {{projectName}}Client({
  apiKey: '{{apiKey}}'
});
\`\`\`
{{else}}
Sign up to get your API key at {{signupUrl}}
{{/if}}

2. Add to Edgit

edgit components add getting-started docs/getting-started.md docs
edgit tag create getting-started v1.0.0
edgit tag set getting-started production v1.0.0
edgit push --tags --force

3. Use in Your Application

import { DocsLoader } from './lib/docs-loader'

const loader = new DocsLoader()
await loader.init(docsMap) // Auto-discovered docs

// Render with variables
const content = await loader.get('getting-started', {
  projectName: 'My API',
  version: '1.0.0',
  nodeVersion: '18',
  hasApiKey: true,
  apiKey: user.apiKey,
  signupUrl: 'https://example.com/signup'
})

YAML Frontmatter

Add metadata to your markdown files:

---
title: Authentication Guide
description: Learn how to authenticate with our API
author: API Team
version: 2.1.0
tags:
  - authentication
  - security
  - oauth
updated: 2025-01-15
---

# Authentication Guide

Your content here...

Access frontmatter in your code:

const doc = docsLoader.getRaw('authentication')
console.log(doc.metadata.title) // "Authentication Guide"
console.log(doc.metadata.tags)  // ["authentication", "security", "oauth"]

Handlebars Features

Variables

Hello {{userName}}, welcome to {{appName}}!

Conditionals

{{#if isPremium}}
## Premium Features
Access advanced analytics and reporting.
{{else}}
## Free Tier
Upgrade to unlock premium features.
{{/if}}

Loops

## Available Endpoints

{{#each endpoints}}
- **{{this.method}}** `{{this.path}}` - {{this.description}}
{{/each}}

Built-in Helpers

# {{capitalize pageName}}

Last updated: {{date lastModified}}

Total users: {{formatNumber userCount}}

Description: {{truncate longDescription 100}}

Status: {{upper status}}

Custom Helpers

docsLoader.registerHelper('apiUrl', (endpoint) => {
  return `https://api.example.com/v1${endpoint}`
})

docsLoader.registerHelper('codeBlock', (lang, code) => {
  return `\`\`\`${lang}\n${code}\n\`\`\``
})

Use in markdown:

API Endpoint: {{apiUrl "/users"}}

{{codeBlock "javascript" exampleCode}}

Partials

docsLoader.registerPartial('header', `
# {{title}}
**Version {{version}}** | Last updated: {{date updated}}
`)

Use in markdown:

{{> header title="API Guide" version="1.0.0" updated=now}}

Your content here...

Auto-Discovery

Docs are automatically discovered at build time via Vite plugin:

// vite.config.ts
import { docsDiscoveryPlugin } from './scripts/vite-plugin-docs-discovery'

export default defineConfig({
  plugins: [
    docsDiscoveryPlugin(), // Auto-discovers docs/**.md files
  ],
})

This generates a virtual module:

// Automatically available in your code
import { docs } from 'virtual:conductor-docs'

// docs contains all .md files from docs/ directory
docs.forEach(doc => {
  console.log(doc.name)    // File name without extension
  console.log(doc.content) // Raw markdown content
})

First-Class Component Pattern

Docs work exactly like prompts/ with the same infrastructure:

Feature	Prompts	Docs
Auto-discovery	✅	✅
Handlebars	✅	✅
Frontmatter	✅	✅
Caching	✅	✅
Versioning	✅	✅
Component refs	✅	✅

// Both use the same pattern
const prompt = await promptManager.renderByName('summarize', vars)
const docs = await docsLoader.get('getting-started', vars)

Versioning Documentation

Semantic Versioning

Follow semver for documentation changes:

Major (v2.0.0): Breaking changes to examples or structure
Minor (v1.1.0): New sections, backwards compatible
Patch (v1.0.1): Typo fixes, clarifications

# Bug fix
edgit tag create getting-started v1.0.1

# New section added
edgit tag create getting-started v1.1.0

# Restructured guide
edgit tag create getting-started v2.0.0

Tagging for Deployment

# Tag for different environments
edgit tag set api-guide canary v2.0.0
edgit tag set api-guide staging v2.0.0
edgit tag set api-guide production v2.0.0

Version-Specific Documentation

# Development
docs: docs/getting-started@latest

# Production
docs: docs/getting-started@production

# Lock to specific version
docs: docs/getting-started@v1.2.3

Integration with Documentation Directory

The docs/ directory is a first-class component in Conductor. Markdown files are auto-discovered and served by the built-in docs-serve ensemble. To customize configuration, create a custom docs ensemble:

# ensembles/docs-custom.yaml
name: docs-custom
description: Customized API Documentation

trigger:
  - type: http
    paths:
      - path: /docs
        methods: [GET]
      - path: /docs/:slug
        methods: [GET]
      - path: /docs/openapi.json
        methods: [GET]
    public: true

flow:
  - name: render
    agent: docs
    config:
      title: My API Documentation
      ui: stoplight
      basePath: /docs
      nav:
        order:
          - getting-started
          - authentication
          - advanced-workflows
          - guides/*
        showReserved:
          agents: true
          ensembles: true
          api: true

output:
  _raw: ${render.output}

Place your markdown guides directly in the docs/ directory:

docs/
├── getting-started.md     # Custom guide (uses Handlebars)
├── authentication.md      # Another guide
└── advanced-workflows.md  # More documentation

Use Cases

API Documentation

---
title: {{apiName}} API Reference
version: {{apiVersion}}
---

# {{apiName}} API

Base URL: `{{baseUrl}}`

## Authentication

All requests require a valid API key:

\`\`\`bash
curl {{baseUrl}}/users \\
  -H "Authorization: Bearer YOUR_API_KEY"
\`\`\`

{{#each endpoints}}
## {{this.name}}

**{{this.method}}** `{{this.path}}`

{{this.description}}

### Example

\`\`\`bash
{{this.example}}
\`\`\`
{{/each}}

User Guides

---
title: {{productName}} User Guide
audience: end-users
---

# Getting Started with {{productName}}

{{#if userTier}}
You're on the **{{userTier}}** plan.
{{/if}}

## Quick Setup

1. Create an account at {{signupUrl}}
2. Install the {{productName}} client
3. Configure your API key

{{#if isPremium}}
## Premium Features

As a premium user, you have access to:
{{#each premiumFeatures}}
- {{this.name}}: {{this.description}}
{{/each}}
{{/if}}

Changelog

---
title: Changelog
type: release-notes
---

# Changelog

## Version {{latestVersion}} - {{releaseDate}}

{{#each changes}}
### {{this.type}}
{{#each this.items}}
- {{this}}
{{/each}}
{{/each}}

## Previous Releases

{{#each previousReleases}}
### {{this.version}} - {{this.date}}
{{this.summary}}
{{/each}}

Best Practices

1. Use Frontmatter for Metadata

---
title: Clear Title
description: Brief description
tags: [api, authentication, oauth]
difficulty: intermediate
estimatedTime: 10 minutes
---

2. Keep Handlebars Simple

✅ Good: Hello {{userName}}!
❌ Bad: {{#if (and (eq userType "premium") (gt credits 100))}}...

3. Version Documentation Like Code

# Version docs with meaningful messages
edgit tag create api-guide v2.0.0 -m "Updated to REST API v2"

4. Test with Real Variables

// Test rendering with actual data
const rendered = await docsLoader.get('guide', {
  projectName: 'Test Project',
  version: '1.0.0'
})
console.assert(rendered.includes('Test Project'))

5. Organize by Audience

docs/
├── users/           # End-user documentation
│   ├── getting-started.md
│   └── faq.md
├── developers/      # Developer guides
│   ├── api-reference.md
│   └── webhooks.md
└── internal/        # Internal documentation
    ├── architecture.md
    └── deployment.md

6. Use Partials for Repeated Content

docsLoader.registerPartial('prerequisites', `
## Prerequisites

- Node.js 18+
- npm or yarn
- API key (get one at {{signupUrl}})
`)

{{> prerequisites signupUrl="https://example.com/signup"}}

Next Steps

Your First Documentation

Create your first docs

Components Overview

Learn about all component types

Prompts

Similar to docs with Handlebars

Edgit

Version control for components

​Overview

​Quick Start

​1. Create a Docs Component

​2. Add to Edgit

​3. Use in Your Application

​YAML Frontmatter

​Handlebars Features

​Variables

​Conditionals

​Loops

​Built-in Helpers

​Custom Helpers

​Partials

​Auto-Discovery

​First-Class Component Pattern

​Versioning Documentation

​Semantic Versioning

​Tagging for Deployment

​Version-Specific Documentation

​Integration with Documentation Directory

​Use Cases

​API Documentation

​User Guides

​Changelog

​Best Practices

​1. Use Frontmatter for Metadata

​2. Keep Handlebars Simple

​3. Version Documentation Like Code

​4. Test with Real Variables

​5. Organize by Audience

​6. Use Partials for Repeated Content

​Next Steps