markitect-main/examples/manpages/enhanced-manpage-schema.json

{
  "$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"]
}