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

---
schema-id: "https://markitect.dev/schemas/manpage/v1.0"
version: "1.0.0"
status: "stable"
domain: "manpage"
description: "JSON schema for Unix-style manual pages with section classification and content control"
---

# Unix Manual Page Schema v1.0

## Overview

This schema defines the structure and validation rules for Unix-style manual pages (manpages) in MarkiTect's markdown format. It includes comprehensive section classification, content control patterns, and quality guidelines to ensure consistent, high-quality documentation.

## Features

- **Section Classification System**: Categorizes manpage sections as required, recommended, optional, discouraged, or improper
- **Content Control**: Validates content patterns, quality metrics, and structural requirements
- **Flexible Section Names**: Supports alternative section names (e.g., "FLAGS" as alternative to "OPTIONS")
- **Quality Enforcement**: Minimum/maximum content requirements for paragraphs, code blocks, and words

## Section Classifications

### Required Sections
- **SYNOPSIS**: Brief command syntax with all options and arguments
- **DESCRIPTION**: Detailed explanation of command purpose and functionality

### Recommended Sections
- **EXAMPLES**: Practical usage examples demonstrating common use cases
- **OPTIONS**: Detailed option descriptions with all flags and behaviors
- **SEE ALSO**: Related commands and documentation references

### Optional Sections
- **BUGS**: Known issues and bug reporting information
- **AUTHORS**: Contributors and maintainers
- **COPYRIGHT**: License information
- **HISTORY**: Historical development information

### Discouraged Sections
- **DEPRECATED**: Legacy content (should move to HISTORY)
- **OLD_SYNTAX**: Outdated syntax (should move to HISTORY or be removed)

### Improper Sections
- **INTERNAL_NOTES**: Development notes (must not appear in published docs)
- **TODO**: Development tasks (remove before publication)
- **DRAFT**: Draft markers (remove before publication)

## Usage

### Validating a Manpage

```bash
markitect validate my-command.1.md --schema manpage-schema-v1.0
```

### Common Validation Errors

1. **Missing Required Sections**: Ensure SYNOPSIS and DESCRIPTION are present
2. **Content Too Brief**: DESCRIPTION should have at least 50 words
3. **No Examples**: While optional, EXAMPLES are highly recommended
4. **Improper Sections**: Remove TODO, DRAFT, and INTERNAL_NOTES before publication

## Content Quality Guidelines

### SYNOPSIS Section
- Show command name in bold: `**command**`
- Use brackets `[]` for optional arguments
- Use italic `*ARG*` for required arguments
- Keep concise (1-5 lines maximum)
- Include 5-150 words

### DESCRIPTION Section
- Start with what the command does
- Explain why users would use it
- Describe main functionality and features
- Minimum 50 words, maximum 1000 words
- At least 3 sentences

### EXAMPLES Section
- Use bash code blocks for commands
- Include comments explaining each example
- Start simple, progress to complex
- Show actual output when helpful
- Cover common use cases first

## Schema Definition

```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"]
}
```

## Version History

### v1.0.0 (2026-01-04)
- Initial markdown schema version
- Migrated from enhanced-manpage JSON schema
- Added comprehensive documentation
- Implemented section classification system
- Added content control and quality guidelines

## Related Documentation

- [Schema Naming Specification](../../roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md)
- [Schema Management Workplan](../../roadmap/schema-of-schemas/WORKPLAN.md)
- [MarkiTect Documentation](../../README.md)