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

# 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

# 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

# Render template with data
markitect template-render invoice.md data.json

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

Advanced Querying

# 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

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