Docs Components

// 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}}

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

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'
})

---
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...

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

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

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

## Available Endpoints

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

# {{capitalize pageName}}

Last updated: {{date lastModified}}

Total users: {{formatNumber userCount}}

Description: {{truncate longDescription 100}}

Status: {{upper status}}

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

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

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

{{codeBlock "javascript" exampleCode}}

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

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

Your content here...

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

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

// 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
})

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

# 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

# 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

# Development
docs: docs/getting-started@latest

# Production
docs: docs/getting-started@production

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

# 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}

docs/
├── getting-started.md     # Custom guide (uses Handlebars)
├── authentication.md      # Another guide
└── advanced-workflows.md  # More 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}}

---
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}}

---
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}}

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

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

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

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

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

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

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

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