tegwick
b51999582e
Add comprehensive example showcasing schema validation with self-documenting manpage system: - markdown-manpage-schema.json: Reusable schema for Unix manpage structure - markdown-schema-validation.1.md: Complete manual about schema validation - README.md: Usage guide, integration examples, and best practices - SCHEMA_EVOLUTION_WORKPLAN.md: Roadmap for enhanced schema system The manual validates against its own schema, demonstrating dogfooding principle. Workplan outlines 5-phase evolution from rigid structural validation to flexible content control with blueprints. Key features demonstrated: - Schema-driven documentation structure - Self-validating documentation - Reusable validation patterns - Classification system design (required/recommended/optional/discouraged/improper) This sets foundation for Phase 1 implementation: enhanced schema format with section classification and content control. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
127 lines
3.7 KiB
JSON
127 lines
3.7 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"type": "object",
|
|
"title": "Markdown Manpage Schema",
|
|
"description": "JSON schema defining the structure of Unix-style manual pages written in Markdown. Compatible with man(1) section format and conventions.",
|
|
"properties": {
|
|
"headings": {
|
|
"type": "object",
|
|
"description": "Document heading structure following Unix manpage conventions",
|
|
"properties": {
|
|
"level_1": {
|
|
"type": "array",
|
|
"description": "Title heading: command(section) - brief description",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9-]+\\([0-9]\\) - .+",
|
|
"description": "Must follow format: command(section) - description"
|
|
},
|
|
"level": {
|
|
"type": "integer",
|
|
"const": 1
|
|
}
|
|
},
|
|
"required": ["content", "level"]
|
|
},
|
|
"minItems": 1,
|
|
"maxItems": 1
|
|
},
|
|
"level_2": {
|
|
"type": "array",
|
|
"description": "Main section headings (SYNOPSIS, DESCRIPTION, etc.)",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Section name in UPPERCASE"
|
|
},
|
|
"level": {
|
|
"type": "integer",
|
|
"const": 2
|
|
}
|
|
},
|
|
"required": ["content", "level"]
|
|
},
|
|
"minItems": 3,
|
|
"maxItems": 30
|
|
},
|
|
"level_3": {
|
|
"type": "array",
|
|
"description": "Subsection headings (optional, for grouping commands or options)",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string"
|
|
},
|
|
"level": {
|
|
"type": "integer",
|
|
"const": 3
|
|
}
|
|
},
|
|
"required": ["content", "level"]
|
|
},
|
|
"minItems": 0,
|
|
"maxItems": 50
|
|
}
|
|
},
|
|
"required": ["level_1", "level_2"]
|
|
},
|
|
"paragraphs": {
|
|
"type": "array",
|
|
"description": "Text paragraphs containing descriptions and explanations",
|
|
"minItems": 5,
|
|
"maxItems": 500
|
|
},
|
|
"lists": {
|
|
"type": "array",
|
|
"description": "Lists for options, examples, or structured information",
|
|
"minItems": 0,
|
|
"maxItems": 100
|
|
},
|
|
"code_blocks": {
|
|
"type": "array",
|
|
"description": "Code examples and command demonstrations",
|
|
"minItems": 1,
|
|
"maxItems": 50
|
|
},
|
|
"emphasis": {
|
|
"type": "array",
|
|
"description": "Bold and italic emphasis for commands, options, and arguments",
|
|
"minItems": 10,
|
|
"maxItems": 500
|
|
}
|
|
},
|
|
"required": ["headings", "paragraphs", "code_blocks", "emphasis"],
|
|
"x-markitect-required-sections": [
|
|
"SYNOPSIS",
|
|
"DESCRIPTION"
|
|
],
|
|
"x-markitect-recommended-sections": [
|
|
"OPTIONS",
|
|
"EXAMPLES",
|
|
"SEE ALSO",
|
|
"COPYRIGHT"
|
|
],
|
|
"x-markitect-optional-sections": [
|
|
"COMMANDS",
|
|
"CONFIGURATION",
|
|
"FILES",
|
|
"EXIT STATUS",
|
|
"ENVIRONMENT",
|
|
"BUGS",
|
|
"AUTHORS"
|
|
],
|
|
"x-markitect-conventions": {
|
|
"heading_case": "UPPERCASE for H2 sections",
|
|
"command_format": "Bold with **command** for commands and options",
|
|
"argument_format": "Italic with *ARG* for arguments and placeholders",
|
|
"example_language": "bash for code blocks",
|
|
"definition_lists": "Use bold followed by colon for FILES, EXIT STATUS, ENVIRONMENT sections"
|
|
}
|
|
}
|