Type-Safe API
Fully typed TypeScript API for safer development
docs-clientMarkdown Document Management
Type-safe, schema-driven documentation for TypeScript
Type-safe, schema-driven documentation for TypeScript
bun add @interactive-inc/docs-client
# or
npm install @interactive-inc/docs-clientGet up and running with minimal setup. This example shows how to read a Markdown file from your documentation.
import { DocClient, DocFileSystem } from '@interactive-inc/docs-client'
// Initialize
const fileSystem = new DocFileSystem({ basePath: './docs' })
const client = new DocClient({ fileSystem })
// Read Markdown
const file = await client.mdFile('guides/getting-started.md').read()
if (file instanceof Error) throw file
console.log(file.content.title())
console.log(file.content.body())Navigate through your documentation structure easily. Directories provide methods to list, filter, and access files.
// Get directory reference
const directory = client.directory('features')
// List all Markdown files
const files = await directory.mdFiles()
// Read specific file
const loginFeature = directory.mdFile('login.md')
const entity = await loginFeature.read()Define type-safe metadata with Zod schemas. This ensures your frontmatter follows a consistent structure across documents.
import { DocSchemaBuilder } from '@interactive-inc/docs-client'
import { z } from 'zod'
const featureSchema = new DocSchemaBuilder()
.addRequired('milestone', z.string())
.addRequired('priority', z.enum(['high', 'medium', 'low']))
.addOptional('assignee', z.string())
.addOptional('tags', z.array(z.string()).default([]))
.build()
// Type-safe file operations
const file = await client.mdFile('features/auth.md', featureSchema).read()
if (file instanceof Error) throw file
const meta = file.content.meta()
console.log(meta.text('milestone')) // string
console.log(meta.text('priority')) // 'high' | 'medium' | 'low'
console.log(meta.multiText('tags')) // string[]Common operations for managing your documentation files programmatically.
Create new documentation files with predefined content and metadata.
// Create new file with default content
const newFile = await directory.createMdFile('new-feature.md')
// Write custom content
const entity = newFile.create({
title: 'New Feature',
body: '# New Feature\n\nDescription here...'
})
await newFile.write(entity)Modify frontmatter without touching the document content.
const file = await client.mdFile('features/login.md').read()
if (file instanceof Error) throw file
// Update frontmatter
const meta = file.content.meta()
const updated = file.withMeta(
meta
.withProperty('status', 'completed')
.withProperty('updated_at', new Date().toISOString())
)
await client.mdFile('features/login.md').write(updated)Instead of deleting files, move them to archive. This preserves document history and allows easy restoration.
// Archive a file (moves to _/ directory)
const fileRef = client.mdFile('old-specs/deprecated.md')
await fileRef.archive()
// Access archived files
const archived = client.directory('old-specs/_').mdFile('deprecated.md')
const content = await archived.read()Powerful features for complex documentation workflows.
Explore your entire documentation structure programmatically.
// Get complete file tree
const tree = await client.fileTree('products')
// Get directories only
const dirs = await client.directoryTree('products')Process multiple files efficiently using async generators.
// Process all files in directory
for await (const file of directory.mdFilesGenerator()) {
const entity = await file.read()
if (entity instanceof Error) continue
// Process each file
console.log(entity.title)
}Customize the behavior of docs-client to match your project structure.
const client = new DocClient({
fileSystem,
config: {
indexFileName: 'index.md', // Default index file
archiveDirectoryName: '_', // Archive directory name
directoryExcludes: ['.git'], // Ignore directories
defaultIndexIcon: '📁', // Icon for index files
}
})