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

Schema File

The manpage schema is now managed in MarkiTect's schema registry:

• Schema Name: manpage-schema-v1.0.md
• Location: markitect/schemas/manpage-schema-v1.0.md
• Format: Markdown with embedded JSON (following schema-of-schemas standard)

This schema defines 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. List Available Schemas

View all registered schemas (including the manpage schema):

markitect schema-list

You should see manpage-schema-v1.0.md listed with a number.

2. Validate the Manual Against the Schema

Verify that the manual conforms to the manpage schema using the new multi-schema validation:

cd examples/manpages

# Validate by schema filename (from registry)
markitect schema-validate manpage-schema-v1.0.md

# Or validate by number (if schema is #2 in the list)
markitect schema-validate 2

# Or validate a specific document file
markitect validate markdown-schema-validation.1.md \
    --schema manpage-schema-v1.0.md

Expected output: ✅ VALID - Document structure matches schema requirements

3. Show Detailed Validation

See detailed validation information:

markitect schema-validate manpage-schema-v1.0.md --detailed-errors

4. Validate Multiple Schemas

Validate all registered schemas at once:

# Validate all schemas
markitect schema-validate --all

# Validate a range of schemas
markitect schema-validate 1-3

# Validate specific schemas
markitect schema-validate 1,3,5

5. Examine the Schema

View the manpage schema in markdown format:

markitect schema-get manpage-schema-v1.0.md

# Or view the file directly
cat ../../markitect/schemas/manpage-schema-v1.0.md

6. Validate Other Manpages

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

# Validate using schema name from registry
markitect validate ../../docs/manuals/markitect.1.md \
    --schema manpage-schema-v1.0.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 manpage-schema-v1.0.md \
        || 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 manpage-schema-v1.0.md \
        --quiet || {
        echo "Manpage validation failed: $manpage"
        markitect validate "$manpage" \
            --schema manpage-schema-v1.0.md \
            --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 manpage-schema-v1.0.md \
			|| 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 markitect/schemas/manpage-schema-v1.0.md command-manpage-schema-v1.0.md
# Edit to require COMMANDS section
markitect schema-validate ./command-manpage-schema-v1.0.md
markitect schema-ingest ./command-manpage-schema-v1.0.md

# For format manpages (section 5)
cp markitect/schemas/manpage-schema-v1.0.md format-manpage-schema-v1.0.md
# Edit to require FORMAT section

# For convention manpages (section 7)
cp markitect/schemas/manpage-schema-v1.0.md convention-manpage-schema-v1.0.md
# Edit to be more flexible

Validate Your Own Documentation

Apply the manpage schema to your project:

# Validate README (if it follows manpage structure)
markitect validate README.md \
    --schema manpage-schema-v1.0.md

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