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.",
  "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"
  }
}