Files

tegwick b81ce5631d feat: implement Phase 2 - Markdown Schema Loader

Completed Phase 2 of the schema-of-schemas implementation with full
markdown schema support. This enables schemas to be authored as
markdown files with rich documentation and embedded JSON schemas.

Core Implementation (markitect/schema_loader.py):
- MarkdownSchemaLoader class with comprehensive parsing capabilities
- YAML frontmatter extraction with error handling
- JSON code block extraction with section preference (## Schema Definition)
- Metadata merging with x-markitect-source tracking
- Schema saving with template support and round-trip capability
- Helper methods: list_json_blocks(), validate_schema_structure()

Test Coverage (tests/test_schema_loader.py):
- 35 comprehensive unit tests (100% passing)
- Tests for loading, parsing, saving, round-trip conversion
- Edge case handling (empty files, binary files, malformed blocks)
- Fixed binary file test to use invalid UTF-8 sequences

Example Schema (markitect/schemas/manpage-schema-v1.0.md):
- First markdown schema following naming convention
- Complete manpage schema with frontmatter + documentation + JSON
- Demonstrates section classification and content control
- Shows proper structure for future schema authors

Documentation (roadmap/schema-of-schemas/SCHEMA_LOADER_GUIDE.md):
- Comprehensive user guide (600+ lines)
- API reference with examples
- Best practices and troubleshooting
- Integration patterns for CLI and validator

Progress Tracking:
- Updated TODO.md with Phase 2 completion
- Updated CHANGELOG.md with implementation details
- Next: Phase 3 - Schema-for-Schemas Metaschema

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-05 00:02:15 +01:00

11 KiB

Raw Blame History

schema-id, version, status, domain, description

schema-id	version	status	domain	description
https://markitect.dev/schemas/manpage/v1.0	1.0.0	stable	manpage	JSON schema for Unix-style manual pages with section classification and content control

Unix Manual Page Schema v1.0

Overview

This schema defines the structure and validation rules for Unix-style manual pages (manpages) in MarkiTect's markdown format. It includes comprehensive section classification, content control patterns, and quality guidelines to ensure consistent, high-quality documentation.

Features

Section Classification System: Categorizes manpage sections as required, recommended, optional, discouraged, or improper
Content Control: Validates content patterns, quality metrics, and structural requirements
Flexible Section Names: Supports alternative section names (e.g., "FLAGS" as alternative to "OPTIONS")
Quality Enforcement: Minimum/maximum content requirements for paragraphs, code blocks, and words

Section Classifications

Required Sections

SYNOPSIS: Brief command syntax with all options and arguments
DESCRIPTION: Detailed explanation of command purpose and functionality

Recommended Sections

EXAMPLES: Practical usage examples demonstrating common use cases
OPTIONS: Detailed option descriptions with all flags and behaviors
SEE ALSO: Related commands and documentation references

Optional Sections

BUGS: Known issues and bug reporting information
AUTHORS: Contributors and maintainers
COPYRIGHT: License information
HISTORY: Historical development information

Discouraged Sections

DEPRECATED: Legacy content (should move to HISTORY)
OLD_SYNTAX: Outdated syntax (should move to HISTORY or be removed)

Improper Sections

INTERNAL_NOTES: Development notes (must not appear in published docs)
TODO: Development tasks (remove before publication)
DRAFT: Draft markers (remove before publication)

Usage

Validating a Manpage

markitect validate my-command.1.md --schema manpage-schema-v1.0

Common Validation Errors

Missing Required Sections: Ensure SYNOPSIS and DESCRIPTION are present
Content Too Brief: DESCRIPTION should have at least 50 words
No Examples: While optional, EXAMPLES are highly recommended
Improper Sections: Remove TODO, DRAFT, and INTERNAL_NOTES before publication

Content Quality Guidelines

SYNOPSIS Section

Show command name in bold: **command**
Use brackets [] for optional arguments
Use italic *ARG* for required arguments
Keep concise (1-5 lines maximum)
Include 5-150 words

DESCRIPTION Section

Start with what the command does
Explain why users would use it
Describe main functionality and features
Minimum 50 words, maximum 1000 words
At least 3 sentences

EXAMPLES Section

Use bash code blocks for commands
Include comments explaining each example
Start simple, progress to complex
Show actual output when helpful
Cover common use cases first

Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Enhanced Markdown Manpage Schema with Classifications",
  "description": "JSON schema for Unix-style manual pages with section classification and content control",
  "x-markitect-sections": {
    "SYNOPSIS": {
      "classification": "required",
      "heading_level": 2,
      "position": "after_title",
      "content_instruction": "Brief command syntax showing all options and arguments in standard format",
      "min_paragraphs": 1,
      "max_paragraphs": 5,
      "min_code_blocks": 0,
      "max_code_blocks": 3,
      "error_message": "SYNOPSIS section is mandatory for all manpages per Unix conventions"
    },
    "DESCRIPTION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Detailed explanation of what the command does, its purpose, and main functionality",
      "min_paragraphs": 2,
      "max_paragraphs": 50,
      "error_message": "DESCRIPTION section is mandatory for all manpages"
    },
    "EXAMPLES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Practical usage examples with explanations demonstrating common use cases",
      "min_code_blocks": 3,
      "max_code_blocks": 20,
      "warning_if_missing": "Examples greatly improve manpage usability - highly recommended"
    },
    "SEE ALSO": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Related commands, configuration files, and documentation references",
      "min_paragraphs": 1,
      "warning_if_missing": "Cross-references help users discover related functionality"
    },
    "OPTIONS": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Detailed option descriptions with all flags and their behaviors",
      "alternatives": ["GLOBAL OPTIONS", "COMMAND OPTIONS", "FLAGS"],
      "warning_if_missing": "Documenting command options helps users understand available functionality"
    },
    "BUGS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Known issues, limitations, and bug reporting information"
    },
    "AUTHORS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "List of contributors and maintainers"
    },
    "COPYRIGHT": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Copyright statement and license information"
    },
    "HISTORY": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Historical information about command development"
    },
    "DEPRECATED": {
      "classification": "discouraged",
      "heading_level": 2,
      "warning_if_missing": "Consider moving deprecated content to historical documentation or HISTORY section"
    },
    "OLD_SYNTAX": {
      "classification": "discouraged",
      "heading_level": 2,
      "warning_if_missing": "Old syntax should be documented in HISTORY or removed entirely"
    },
    "INTERNAL_NOTES": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "Internal notes must not appear in published manpages - move to developer documentation"
    },
    "TODO": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "TODO sections are for development only - remove before publication"
    },
    "DRAFT": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "DRAFT markers must be removed before publication"
    }
  },
  "x-markitect-content-control": {
    "synopsis": {
      "required_patterns": [
        "\\*\\*[a-z][a-z0-9-]*\\*\\*",
        "\\[.*\\]"
      ],
      "discouraged_patterns": [
        "TODO",
        "FIXME",
        "TBD"
      ],
      "content_quality": {
        "min_words": 5,
        "max_words": 150,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Show command name in bold (e.g., **command**)",
        "Use brackets [] for optional arguments",
        "Use italic *ARG* for required arguments",
        "Keep synopsis concise (1-5 lines maximum)",
        "Use ellipsis ... to indicate repeatable arguments"
      ]
    },
    "description": {
      "discouraged_patterns": [
        "TODO",
        "FIXME",
        "\\bWIP\\b",
        "\\bXXX\\b"
      ],
      "forbidden_patterns": [
        "password\\s*=\\s*[\"'].*[\"']",
        "api[_-]?key\\s*=\\s*[\"'].*[\"']",
        "secret\\s*=\\s*[\"'].*[\"']"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 1000,
        "readability_target": "technical",
        "min_sentences": 3
      },
      "content_instructions": [
        "Start with what the command does",
        "Explain why users would use it",
        "Describe main functionality and features",
        "Mention any prerequisites or requirements",
        "Keep technical but accessible"
      ],
      "link_validation": {
        "check_internal": true,
        "check_external": false,
        "allow_fragments": true
      }
    },
    "examples": {
      "required_patterns": [
        "```",
        "#"
      ],
      "content_quality": {
        "min_words": 100,
        "max_words": 2000,
        "readability_target": "general"
      },
      "content_instructions": [
        "Use bash code blocks for command examples",
        "Include comments explaining what each example does",
        "Start with simple examples, progress to complex",
        "Show actual output when helpful",
        "Cover common use cases first"
      ]
    }
  },
  "type": "object",
  "properties": {
    "headings": {
      "type": "object",
      "description": "Document heading structure",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Title heading in format: command(section) - description",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": "^[a-z0-9-]+\\([0-9]\\) - .+"
              }
            }
          },
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "Main section headings",
          "minItems": 3,
          "maxItems": 30
        },
        "level_3": {
          "type": "array",
          "description": "Subsection headings",
          "minItems": 0,
          "maxItems": 50
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "description": "Text paragraphs",
      "minItems": 10,
      "maxItems": 500
    },
    "code_blocks": {
      "type": "array",
      "description": "Code examples",
      "minItems": 1,
      "maxItems": 50
    },
    "lists": {
      "type": "array",
      "description": "Lists for options and structured information",
      "minItems": 0,
      "maxItems": 100
    },
    "emphasis": {
      "type": "array",
      "description": "Bold and italic text for commands and arguments",
      "minItems": 20,
      "maxItems": 500
    }
  },
  "required": ["headings", "paragraphs", "code_blocks", "emphasis"]
}

Version History

v1.0.0 (2026-01-04)

Initial markdown schema version
Migrated from enhanced-manpage JSON schema
Added comprehensive documentation
Implemented section classification system
Added content control and quality guidelines

11 KiB Raw Blame History