markitect-main/docs/manuals/markitect.1.md

# markitect(1) - Advanced Markdown Engine for Structured Content

## SYNOPSIS

**markitect** [*GLOBAL_OPTIONS*] *COMMAND* [*ARGS*...]

## DESCRIPTION

MarkiTect is an advanced markdown engine that transforms markdown files from plain text into intelligent, structured data with performance optimization, schema validation, and relational querying capabilities.

MarkiTect treats documentation as a database rather than simple text files, providing AST caching, frontmatter processing, schema validation, and SQL-like querying capabilities.

## GLOBAL OPTIONS

**-v, --verbose**
: Enable verbose output for detailed operation information

**--config** *PATH*
: Specify path to configuration file (default: auto-detected)

**--database** *PATH*
: Specify path to database file (default: markitect.db)

**--help**
: Show help message and exit

## COMMANDS

### Document Processing

**ingest** *FILE*
: Process and store a markdown file in the database
: Parses frontmatter, content, and tailmatter; generates AST; stores metadata

**get** *FILE*
: Retrieve and output a processed markdown file
: Returns the stored version with all processing applied

**list**
: List all stored files and their status
: Shows ingestion date, file size, and processing status

**metadata** *FILE*
: Display file metadata and frontmatter
: Shows extracted frontmatter, contentmatter, and tailmatter

**modify** *FILE*
: Modify the content of a processed markdown file
: Interactive editor for making changes to stored content

### Content Analysis

**content-get** *FILE*
: Extract content without frontmatter and tailmatter
: Returns clean content body only

**content-stats** *FILE*
: Calculate content statistics
: Word count, character count, reading time estimation

**frontmatter-get** *FILE* *KEY*
: Get specific frontmatter value by key (supports dot notation)
: Example: frontmatter-get doc.md author.name

**frontmatter-keys** *FILE*
: List all frontmatter keys
: Shows all available frontmatter fields

**frontmatter-set** *FILE* *KEY=VALUE*
: Set frontmatter value (supports nested keys)
: Example: frontmatter-set doc.md author.name="John Doe"

**frontmatter-stats** *FILES...*
: Calculate frontmatter statistics across multiple files
: Frequency analysis of frontmatter usage

### Advanced Content Features

**contentmatter-get** *FILE* *KEY*
: Get MultiMarkdown key-value pairs embedded in content
: Extracts inline metadata from document body

**contentmatter-keys** *FILE*
: List all contentmatter keys (MultiMarkdown format)
: Shows embedded key-value pairs

**contentmatter-set** *FILE* *KEY=VALUE*
: Set contentmatter value (adds to document if missing)
: Embeds metadata directly in content

**tailmatter-get** *FILE* *KEY*
: Get specific tailmatter value (QA checklists, metadata)
: Extracts end-of-document metadata

**tailmatter-check** *FILE*
: Run QA checklist validation
: Validates document against tailmatter requirements

### AST Operations

**ast-show** *FILE*
: Display AST structure for file
: Shows parsed abstract syntax tree

**ast-query** *FILE* *JSONPATH*
: Query AST using JSONPath expressions
: Example: ast-query doc.md "$.children[?(@.type=='heading')]"

**ast-stats** *FILES...*
: Show AST statistics for files or entire AST subsystem
: Performance metrics and structure analysis

### Schema Management

**schema-generate** *FILE*
: Generate JSON schema from markdown file's AST structure
: Creates reusable schema for document validation

**schema-ingest** *SCHEMA_FILE*
: Read and store a JSON schema file in the database
: Registers schema for validation use

**schema-list**
: List all stored schema files
: Shows available schemas and their usage

**schema-get** *SCHEMA_NAME*
: Retrieve and output a stored schema file
: Returns JSON schema definition

**schema-delete** *SCHEMA_NAME*
: Delete a stored schema file from the database
: Removes schema and validation rules

**validate** *FILE* *SCHEMA*
: Validate a markdown file against a JSON schema
: Checks document structure and content compliance

### Template System

**template-render** *TEMPLATE* *DATA*
: Render a template with data to generate documents
: Supports `{{variable}}` syntax and nested object access

**generate-stub** *SCHEMA*
: Generate a markdown stub/template from a JSON schema
: Creates document template from schema definition

**generate-drafts** *SCHEMA* *COUNT*
: Generate multiple document drafts from a schema template
: Batch document generation for workflows

### Performance Management

**perf-benchmark** [*OPTIONS*]
: Run performance benchmarks and measure system performance
: Tests template rendering, database operations, and ingestion speed

**perf-validate** [*OPTIONS*]
: Validate system performance against defined thresholds
: Ensures performance meets requirements

**perf-monitor** [*OPTIONS*]
: Monitor system performance over time
: Real-time performance tracking

**perf-track** [*OPTIONS*]
: Record a performance snapshot and track it over time
: Historical performance data collection

**perf-history** [*OPTIONS*]
: Show performance history and trend analysis
: Performance regression detection and reporting

### Database Operations

**db-query** *SQL*
: Execute SQL query against the database
: Direct database access for advanced queries

**db-schema**
: Show database schema and table structure
: Database introspection and documentation

**db-stats**
: Show database statistics and information
: Database size, table counts, performance metrics

**db-data** *FILE*
: Display complete file data including metadata and relationships
: Comprehensive file information

**db-delete**
: Delete the database file
: Complete database reset (use with caution)

### Cache Management

**cache-stats**
: Display cache statistics and effectiveness
: Shows hit rates, memory usage, and performance impact

**cache-clean**
: Clear cache and free memory
: Removes all cached data for fresh processing

**cache-invalidate** *FILE*
: Invalidate specific file cache
: Forces reprocessing of individual files

### System Information

**stats** [*FILE*]
: Show core system statistics or file-specific statistics
: Overview of system status and file processing metrics

**config-stats**
: Display configuration statistics and status
: Shows current configuration and settings

### Associated Files

**associated-files** *SUBCOMMAND*
: Manage associated markdown and schema file pairs
: Link documents with their schemas and templates

### Legacy Support

**legacy** *SUBCOMMAND*
: Manage legacy interface compatibility and lifecycle
: Backward compatibility for older integrations

## EXAMPLES

### Basic Document Processing
```bash
# Process a markdown file
markitect ingest document.md

# List all processed files
markitect list

# Get file metadata
markitect metadata document.md

# Extract frontmatter value
markitect frontmatter-get document.md title
```

### Schema-Driven Development
```bash
# Generate schema from document
markitect schema-generate document.md

# Create document template from schema
markitect generate-stub my-schema.json

# Validate document against schema
markitect validate document.md my-schema.json
```

### Template Processing
```bash
# Render template with data
markitect template-render invoice.md data.json

# Generate multiple drafts
markitect generate-drafts schema.json 10
```

### Advanced Querying
```bash
# Query AST structure
markitect ast-query document.md "$.children[?(@.type=='heading')]"

# SQL database queries
markitect db-query "SELECT * FROM files WHERE frontmatter LIKE '%author%'"

# Content analysis
markitect content-stats document.md
```

### Performance Monitoring
```bash
# Benchmark system performance
markitect perf-benchmark --test-type all

# Track performance over time
markitect perf-track --notes "After optimization"

# View performance history
markitect perf-history --trend-days 30
```

## CONFIGURATION

MarkiTect uses a hierarchical configuration system:

1. **Command-line options** (highest priority)
2. **Environment variables** (`MARKITECT_*`)
3. **Configuration files** (.markitect.yml, markitect.conf)
4. **Default values** (lowest priority)

### Configuration Files
- `~/.markitect/config.yml` - User configuration
- `.markitect.yml` - Project-specific configuration
- Environment variable `MARKITECT_CONFIG` - Custom config path

### Common Configuration Options
- `database_path` - Database file location
- `cache_enabled` - Enable/disable AST caching
- `performance_tracking` - Enable performance monitoring
- `default_schema` - Default schema for validation

## FILES

**markitect.db**
: Default database file for storing processed documents and metadata

**~/.markitect/**
: User configuration directory

**.markitect.yml**
: Project-specific configuration file

**.markitect/**
: Project-specific data directory

## EXIT STATUS

**0**
: Success

**1**
: General error (file not found, validation failure, etc.)

**2**
: Configuration error

**3**
: Database error

**4**
: Schema validation error

## ENVIRONMENT

**MARKITECT_CONFIG**
: Path to configuration file

**MARKITECT_DATABASE**
: Path to database file

**MARKITECT_CACHE_DIR**
: Cache directory location

**MARKITECT_VERBOSE**
: Enable verbose output (any non-empty value)

## SEE ALSO

**tddai**(1), **issue**(1)

Related documentation:
- MarkiTect Architecture Guide
- Schema Development Guide
- Template System Documentation
- Performance Optimization Guide

## BUGS

Report bugs at: https://github.com/markitect/markitect/issues

## AUTHORS

MarkiTect development team

## COPYRIGHT

Copyright (c) 2025 MarkiTect Project. Licensed under MIT License.