markitect-main/examples/manpages

Unix Manpage Schema Validation Example

This example demonstrates MarkiTect's schema validation system by creating a self-validating documentation set: a schema that defines Unix manpage structure and a comprehensive manual about schema validation that validates against its own schema definition.

Overview

This example showcases the "dogfooding" principle - using MarkiTect's schema validation to document schema validation itself. It demonstrates:

• Schema-driven documentation - Defining document structure with JSON Schema
• Self-validation - The manual validates against the manpage schema it demonstrates
• Reusable patterns - The manpage schema can validate any Unix-style manual page
• Complete workflow - From schema creation through validation and refinement

Files in This Example

markdown-manpage-schema.json

A JSON Schema defining the structure of Unix-style manual pages written in Markdown.

Key Features:

• Validates H1 title format: command(section) - description
• Requires SYNOPSIS and DESCRIPTION sections
• Validates heading hierarchy (H1, H2, H3, H4)
• Ensures presence of code examples, paragraphs, and emphasis
• Includes custom x-markitect-* extensions for manpage conventions

Schema Requirements:

• Exactly 1 H1 heading (document title)
• 3-30 H2 headings (major sections)
• 0-50 H3 headings (subsections)
• 5-500 paragraphs (content)
• 1-50 code blocks (examples)
• 10-500 emphasis elements (commands/arguments)

markdown-schema-validation.1.md

A comprehensive manual page (section 7) documenting MarkiTect's markdown schema validation system.

Sections Include:

• SYNOPSIS - Command syntax reference
• DESCRIPTION - How schema validation works
• SCHEMA STRUCTURE - JSON Schema format details
• COMMANDS - Schema management and validation commands
• WORKFLOW - Step-by-step validation workflows
• VALIDATION RULES - What schemas validate
• ERROR HANDLING - Understanding validation errors
• SCHEMA DESIGN - Best practices and anti-patterns
• INTEGRATION - CI/CD, git hooks, build systems
• EXAMPLES - Practical usage demonstrations
• Plus standard manpage sections: FILES, EXIT STATUS, ENVIRONMENT, SEE ALSO, etc.

Statistics:

• 19 H2 sections
• 24 H3 subsections
• 147 paragraphs
• 23 code examples
• 105 emphasis markers

Running the Example

1. Validate the Manual Against the Schema

Verify that the manual conforms to the manpage schema:

cd examples/manpages

markitect validate markdown-schema-validation.1.md \
    --schema markdown-manpage-schema.json

Expected output: ✅ VALID - Document structure matches schema requirements

2. Show Detailed Validation

See detailed validation information:

markitect validate markdown-schema-validation.1.md \
    --schema markdown-manpage-schema.json \
    --detailed-errors

3. Generate Schema from the Manual

Analyze the manual's actual structure:

markitect schema-generate markdown-schema-validation.1.md \
    --output actual-structure-schema.json

cat actual-structure-schema.json

Compare the generated schema with the manpage schema to see how the manual conforms.

4. Examine AST Structure

View the parsed structure of the manual:

markitect ast-show markdown-schema-validation.1.md --format tree

Or in compact format:

markitect ast-show markdown-schema-validation.1.md --format compact | head -50

5. Store Schema for Reuse

Add the manpage schema to MarkiTect's database:

markitect schema-ingest markdown-manpage-schema.json
markitect schema-list

6. Validate Other Manpages

Use the schema to validate other manual pages in the project:

markitect validate ../../docs/manuals/markitect.1.md \
    --schema markdown-manpage-schema.json

markitect validate ../../docs/manuals/issue.1.md \
    --schema markdown-manpage-schema.json

7. Generate Manpage Template

Create a template for new manpages:

markitect generate-stub markdown-manpage-schema.json \
    --output new-manpage-template.md

cat new-manpage-template.md

What This Example Demonstrates

1. Schema-Driven Documentation

The manpage schema defines what a valid Unix manual page looks like:

• Required structural elements (title, synopsis, description)
• Heading hierarchy constraints
• Content density requirements (minimum paragraphs, code examples)
• Formatting conventions (bold commands, italic arguments)

2. Self-Validating System

The schema validation manual validates against the manpage schema, proving:

• The schema is practical and usable
• The manual follows manpage conventions
• Schema validation works as documented
• The system is reliable enough to document itself

3. Structural vs Semantic Validation

The schema validates structure, not content:

• ✅ Validates: Correct number of sections, heading levels, code examples present
• ❌ Does not validate: Grammar, code correctness, factual accuracy, logical flow

This distinction is crucial for understanding what schemas can and cannot do.

4. Reusable Patterns

The manpage schema is a reusable pattern that can:

• Validate any Unix-style manual page
• Enforce documentation consistency across a project
• Generate templates for new documentation
• Integrate into CI/CD pipelines for quality checks

5. Custom Schema Extensions

The schema demonstrates MarkiTect's custom extensions:

"x-markitect-required-sections": [
  "SYNOPSIS",
  "DESCRIPTION"
],
"x-markitect-recommended-sections": [
  "OPTIONS",
  "EXAMPLES",
  "SEE ALSO"
],
"x-markitect-conventions": {
  "heading_case": "UPPERCASE for H2 sections",
  "command_format": "Bold with **command**",
  "argument_format": "Italic with *ARG*"
}

These extensions provide metadata about schema intent and conventions beyond structural validation.

Validation Workflow Demonstrated

This example shows the complete schema validation workflow:

Step 1: Schema Creation

• Analyze existing manpages (markitect.1.md, issue.1.md)
• Identify common structural patterns
• Generate base schema from example document
• Refine schema to be flexible yet meaningful

Step 2: Schema Refinement

• Adjust minItems/maxItems for appropriate ranges
• Add custom MarkiTect extensions
• Include heading patterns and conventions
• Balance strictness with flexibility

Step 3: Document Creation

• Write document following schema structure
• Use template generated from schema as starting point
• Ensure all required sections present
• Include appropriate code examples and formatting

Step 4: Validation

• Validate document against schema
• Review validation errors if any
• Fix structural issues
• Re-validate until passing

Step 5: Iteration

• Refine schema based on validation experience
• Adjust constraints for real-world use cases
• Document lessons learned
• Share schema for reuse

Integration Examples

CI/CD Integration

Add to .github/workflows/docs.yml or similar:

- name: Validate Manpages
  run: |
    for manpage in docs/manuals/*.md; do
      markitect validate "$manpage" \
        --schema examples/manpages/markdown-manpage-schema.json \
        || exit 1
    done

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
changed_manpages=$(git diff --cached --name-only --diff-filter=ACM | grep 'docs/manuals/.*\.md$')

for manpage in $changed_manpages; do
    markitect validate "$manpage" \
        --schema examples/manpages/markdown-manpage-schema.json \
        --quiet || {
        echo "Manpage validation failed: $manpage"
        markitect validate "$manpage" \
            --schema examples/manpages/markdown-manpage-schema.json \
            --detailed-errors
        exit 1
    }
done

Makefile Integration

Add to project Makefile:

.PHONY: validate-manpages
validate-manpages:
	@echo "Validating manual pages..."
	@for manpage in docs/manuals/*.md; do \
		markitect validate "$$manpage" \
			--schema examples/manpages/markdown-manpage-schema.json \
			|| exit 1; \
	done
	@echo "✅ All manpages valid"

.PHONY: docs
docs: validate-manpages
	# Continue with doc generation...

Key Lessons from This Example

1. Start with Real Documents

The manpage schema was created by analyzing existing manpages (markitect.1.md, issue.1.md), not designed in isolation. This ensures the schema reflects real-world usage.

2. Use Ranges, Not Exact Counts

The schema uses ranges like 5-500 paragraphs instead of exact counts. This provides flexibility while still enforcing quality standards.

3. Required vs Recommended

The schema distinguishes between required sections (SYNOPSIS, DESCRIPTION) and recommended sections (EXAMPLES, SEE ALSO), allowing flexibility where appropriate.

4. Validate Structure, Not Semantics

Schemas validate document structure, not content quality. Grammar checking, code correctness, and factual accuracy require other tools.

5. Progressive Refinement

Schemas should evolve based on validation experience. Start loose, tighten based on actual needs, never over-specify.

6. Documentation is Essential

The schema includes extensive metadata about conventions and intent through custom extensions, making it self-documenting.

Extending This Example

Create Schema Variants

Create specialized schemas for different manpage types:

# For command manpages (section 1)
cp markdown-manpage-schema.json command-manpage-schema.json
# Edit to require COMMANDS section

# For format manpages (section 5)
cp markdown-manpage-schema.json format-manpage-schema.json
# Edit to require FORMAT section

# For convention manpages (section 7)
cp markdown-manpage-schema.json convention-manpage-schema.json
# Edit to be more flexible

Validate Your Own Documentation

Apply the manpage schema to your project:

# Validate README
markitect validate README.md \
    --schema markdown-manpage-schema.json

# May need adjustments for non-manpage docs

Generate Schema Family

Create schemas for related document types:

• API documentation schema
• Tutorial schema
• RFC/specification schema
• Architecture decision record (ADR) schema

Each can follow similar validation principles while enforcing type-specific structure.

Further Reading

• markdown-schema-validation.1.md - Complete reference for schema validation
• ../../docs/manuals/markitect.1.md - MarkiTect command reference
• JSON Schema Specification - https://json-schema.org/
• Unix Manual Page Conventions - man 7 man-pages on Unix systems

Validation Results

This example has been validated to confirm:

✅ Manual validates against manpage schema ✅ Schema is well-formed JSON Schema draft-07 ✅ All required sections present in manual ✅ Heading hierarchy follows Unix conventions ✅ Code examples demonstrate actual usage ✅ Structure matches defined constraints

License

Part of the MarkiTect project. Licensed under MIT License.

---

Note: This example represents a complete, production-ready use case of MarkiTect's schema validation system. The files can be used as-is or adapted for your own documentation requirements.