markitect-main/examples/schemas/manpage-schema-v1.md

Manpage Schema v1.0

Schema ID: https://markitect.dev/schemas/manpage/v1 Version: 1.0.0 Status: Stable Created: 2026-01-04 Document Types: Manual pages, CLI documentation

Overview

This schema validates Unix/Linux manual page documentation following standard conventions. Manual pages (man pages) are the traditional form of documentation for Unix commands and system calls.

Typical Structure

A well-formed manual page includes:

1. NAME - Command name and one-line description
2. SYNOPSIS - Command syntax showing all options
3. DESCRIPTION - Detailed explanation of what the command does
4. OPTIONS - Description of each command-line option
5. EXAMPLES - Practical usage examples
6. SEE ALSO - Related commands or documentation

Usage

Validate a Manpage

markitect validate mycommand.1.md --schema manpage-schema-v1

Generate Manpage Template

markitect generate-stub manpage-schema-v1.json --output newcommand.1.md

Refine Existing Schema

markitect schema-refine manpage-schema-v1.json --loosen-counts

Examples

Complete examples can be found in:

• examples/manpages/markdown-schema-validation.1.md

Validation Rules

Required Sections (Level 2 Headings)

NAME

• Classification: Required
• Content: Command name in bold followed by brief description
• Format: **command** - one line description
• Example: **markitect** - validate and analyze markdown documents

SYNOPSIS

• Classification: Required
• Content: Command syntax with all options
• Min code blocks: 1
• Max paragraphs: 3
• Example:

  markitect [OPTIONS] COMMAND [ARGS]
  

DESCRIPTION

• Classification: Required
• Content: Detailed explanation of the command
• Min paragraphs: 2
• Min words: 50

Recommended Sections

OPTIONS

• Classification: Recommended
• Content: Definition list or table of command-line options
• Format: Each option as **--option** *type* followed by description

EXAMPLES

• Classification: Recommended
• Content: Practical usage examples with explanations
• Min code blocks: 1
• Benefit: Greatly improves documentation usability

Optional Sections

ENVIRONMENT

• Environment variables affecting command behavior

FILES

• Important files used or created by the command

EXIT STATUS

• Explanation of exit codes

BUGS

• Known issues or limitations

AUTHORS

• Command authors and contributors

SEE ALSO

• Related commands or documentation

Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/manpage/v1",
  "version": "1.0.0",
  "title": "Unix Manual Page Schema",
  "description": "Schema for validating Unix/Linux manual page documentation",
  "type": "object",
  "properties": {
    "headings": {
      "type": "object",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Document title (command name)",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": ".*"
              }
            }
          },
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "Section headings",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "enum": [
                  "NAME",
                  "SYNOPSIS",
                  "DESCRIPTION",
                  "OPTIONS",
                  "EXAMPLES",
                  "ENVIRONMENT",
                  "FILES",
                  "EXIT STATUS",
                  "BUGS",
                  "AUTHORS",
                  "SEE ALSO"
                ]
              }
            }
          },
          "minItems": 3,
          "maxItems": 20
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "description": "Paragraph content",
      "items": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "minItems": 3
    },
    "code_blocks": {
      "type": "array",
      "description": "Code examples and command syntax",
      "items": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        }
      },
      "minItems": 1
    }
  },
  "required": ["headings", "paragraphs"],
  "x-markitect-sections": {
    "NAME": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Command name in bold followed by brief description",
      "pattern": "\\*\\*[a-z-]+\\*\\*.*",
      "error_if_missing": "NAME section is required in all manual pages"
    },
    "SYNOPSIS": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Command syntax showing all options and arguments",
      "min_code_blocks": 1,
      "error_if_missing": "SYNOPSIS section is required to show command usage"
    },
    "DESCRIPTION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Detailed explanation of what the command does and when to use it",
      "min_paragraphs": 2,
      "min_words": 50,
      "error_if_missing": "DESCRIPTION section is required for detailed explanation"
    },
    "OPTIONS": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Description of each command-line option with syntax and explanation",
      "warning_if_missing": "OPTIONS section recommended for commands with options"
    },
    "EXAMPLES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Practical usage examples with explanations",
      "min_code_blocks": 1,
      "warning_if_missing": "EXAMPLES greatly improve documentation usability"
    },
    "ENVIRONMENT": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Environment variables that affect command behavior"
    },
    "FILES": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Important files used or created by the command"
    },
    "SEE ALSO": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Related commands or documentation references"
    }
  },
  "x-markitect-content-control": {
    "name_section": {
      "required_pattern": "\\*\\*[a-z-]+\\*\\*",
      "description": "Command name must be in bold",
      "example": "**markitect** - validate and analyze markdown documents"
    },
    "synopsis_section": {
      "min_code_blocks": 1,
      "code_block_language": "bash",
      "description": "Must include at least one code block showing command syntax"
    },
    "description_section": {
      "min_paragraphs": 2,
      "min_words": 50,
      "description": "Detailed description with at least 50 words across 2+ paragraphs"
    }
  },
  "x-markitect-metadata": {
    "schema-type": "document-schema",
    "domain": "manpage",
    "document-types": ["manual-page", "man-page", "cli-documentation"],
    "version": "1.0.0",
    "author": "MarkiTect Project",
    "created": "2026-01-04",
    "updated": "2026-01-04",
    "example": "examples/manpages/markdown-schema-validation.1.md",
    "supersedes": null,
    "superseded-by": null
  }
}

Version History

v1.0.0 (2026-01-04)

• Initial stable release
• Validates standard manpage sections
• Classification system (required/recommended/optional)
• Content control for NAME, SYNOPSIS, DESCRIPTION
• MarkiTect extensions for improved validation

Future Enhancements

Planned for v2.0:

• Multi-language support (internationalization)
• Extended sections (DIAGNOSTICS, SECURITY, STANDARDS)
• Cross-reference validation
• Version-specific section variants (man1, man5, man8)

Contributing

To suggest improvements to this schema:

1. Open an issue describing the enhancement
2. Provide example documents demonstrating the need
3. Propose specific schema changes

License

This schema is part of the MarkiTect project and follows the same license.