> ## Documentation Index > Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt > Use this file to discover all available pages before exploring further. # Docs Components > Reusable markdown documentation with Handlebars rendering **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: ```markdown theme={null} // 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 ```bash theme={null} 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 ```typescript theme={null} 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: ```markdown theme={null} --- 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: ```typescript theme={null} const doc = docsLoader.getRaw('authentication') console.log(doc.metadata.title) // "Authentication Guide" console.log(doc.metadata.tags) // ["authentication", "security", "oauth"] ``` ## Handlebars Features ### Variables ```markdown theme={null} Hello {{userName}}, welcome to {{appName}}! ``` ### Conditionals ```markdown theme={null} {{#if isPremium}} ## Premium Features Access advanced analytics and reporting. {{else}} ## Free Tier Upgrade to unlock premium features. {{/if}} ``` ### Loops ```markdown theme={null} ## Available Endpoints {{#each endpoints}} - **{{this.method}}** `{{this.path}}` - {{this.description}} {{/each}} ``` ### Built-in Helpers ```markdown theme={null} # {{capitalize pageName}} Last updated: {{date lastModified}} Total users: {{formatNumber userCount}} Description: {{truncate longDescription 100}} Status: {{upper status}} ``` ### Custom Helpers Register your own helpers: ```typescript theme={null} docsLoader.registerHelper('apiUrl', (endpoint) => { return `https://api.example.com/v1${endpoint}` }) docsLoader.registerHelper('codeBlock', (lang, code) => { return `\`\`\`${lang}\n${code}\n\`\`\`` }) ``` Use in markdown: ```markdown theme={null} API Endpoint: {{apiUrl "/users"}} {{codeBlock "javascript" exampleCode}} ``` ### Partials Register reusable snippets: ```typescript theme={null} docsLoader.registerPartial('header', ` # {{title}} **Version {{version}}** | Last updated: {{date updated}} `) ``` Use in markdown: ```markdown theme={null} {{> 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: ```typescript theme={null} // 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: ```typescript theme={null} // 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 | ✅ | ✅ | ```typescript theme={null} // 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```yaml theme={null} # 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: ```yaml theme={null} # 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 ```markdown theme={null} --- 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 ```markdown theme={null} --- 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 ```markdown theme={null} --- 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 ```markdown theme={null} --- title: Clear Title description: Brief description tags: [api, authentication, oauth] difficulty: intermediate estimatedTime: 10 minutes --- ``` ### 2. Keep Handlebars Simple ```markdown theme={null} ✅ Good: Hello {{userName}}! ❌ Bad: {{#if (and (eq userType "premium") (gt credits 100))}}... ``` ### 3. Version Documentation Like Code ```bash theme={null} # Version docs with meaningful messages edgit tag create api-guide v2.0.0 -m "Updated to REST API v2" ``` ### 4. Test with Real Variables ```typescript theme={null} // 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 ```typescript theme={null} docsLoader.registerPartial('prerequisites', ` ## Prerequisites - Node.js 18+ - npm or yarn - API key (get one at {{signupUrl}}) `) ``` ```markdown theme={null} {{> prerequisites signupUrl="https://example.com/signup"}} ``` ## Next Steps Create your first docs Learn about all component types Similar to docs with Handlebars Version control for components