markitect-main/examples/manpages/markdown-manpage-schema.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.",
  "x-markitect-sections": {
    "SYNOPSIS": {
      "classification": "required",
      "heading_level": 2,
      "position": "after_title",
      "content_instruction": "Brief command syntax showing options and arguments in standard Unix format",
      "min_paragraphs": 1,
      "max_paragraphs": 5,
      "error_message": "SYNOPSIS section is mandatory for all Unix manual pages"
    },
    "DESCRIPTION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Detailed explanation of the command's purpose and functionality",
      "min_paragraphs": 2,
      "error_message": "DESCRIPTION section is mandatory for all Unix manual pages"
    },
    "OPTIONS": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Command-line options and flags with descriptions",
      "alternatives": ["GLOBAL OPTIONS", "COMMAND OPTIONS", "FLAGS"],
      "warning_if_missing": "Documenting command options improves usability"
    },
    "EXAMPLES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Practical usage examples demonstrating common use cases",
      "min_code_blocks": 2,
      "warning_if_missing": "Examples significantly improve manpage usability and comprehension"
    },
    "SEE ALSO": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Related commands, configuration files, and documentation references",
      "warning_if_missing": "Cross-references help users discover related functionality"
    },
    "COPYRIGHT": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Copyright statement and license information",
      "warning_if_missing": "License information should be documented for clarity"
    },
    "COMMANDS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Subcommands and their brief descriptions"
    },
    "CONFIGURATION": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Configuration file format and options"
    },
    "FILES": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Important files used by the command with their purposes"
    },
    "EXIT STATUS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Exit codes and their meanings"
    },
    "ENVIRONMENT": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Environment variables used or set by the command"
    },
    "BUGS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Known issues and bug reporting instructions"
    },
    "AUTHORS": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "List of contributors and maintainers"
    }
  },
  "x-markitect-content-control": {
    "synopsis": {
      "required_patterns": [
        "\\*\\*[a-z][a-z0-9-]*\\*\\*",
        "\\[.*\\]"
      ],
      "discouraged_patterns": [
        "TODO",
        "FIXME"
      ],
      "content_quality": {
        "min_words": 5,
        "max_words": 150,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Show command name in bold: **command**",
        "Use brackets [] for optional arguments",
        "Use italic *ARG* for required arguments",
        "Keep synopsis concise (1-5 lines)",
        "Follow man(1) synopsis conventions"
      ]
    },
    "description": {
      "discouraged_patterns": [
        "TODO",
        "FIXME",
        "\\bWIP\\b",
        "TBD"
      ],
      "forbidden_patterns": [
        "password\\s*=\\s*[\"'].*[\"']",
        "api[_-]?key\\s*=\\s*[\"'].*[\"']"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 1000,
        "readability_target": "technical",
        "min_sentences": 3
      },
      "content_instructions": [
        "Explain what the command does",
        "Describe the primary purpose",
        "Mention key features and capabilities",
        "Note any prerequisites or dependencies",
        "Keep language clear and technical"
      ]
    },
    "examples": {
      "required_patterns": [
        "```",
        "#"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 2000,
        "readability_target": "general"
      },
      "content_instructions": [
        "Use bash code blocks with syntax highlighting",
        "Include comments explaining each example",
        "Start with simple examples, progress to complex",
        "Show actual output when helpful",
        "Cover the most common use cases"
      ]
    }
  },
  "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"]
}