diff --git a/examples/manpages/README.md b/examples/manpages/README.md index 10a8c56e..8171d74a 100644 --- a/examples/manpages/README.md +++ b/examples/manpages/README.md @@ -13,9 +13,14 @@ This example showcases the "dogfooding" principle - using MarkiTect's schema val ## Files in This Example -### `markdown-manpage-schema.json` +### Schema File -A JSON Schema defining the structure of Unix-style manual pages written in Markdown. +The manpage schema is now managed in MarkiTect's schema registry: +- **Schema Name**: `manpage-schema-v1.0.md` +- **Location**: `markitect/schemas/manpage-schema-v1.0.md` +- **Format**: Markdown with embedded JSON (following schema-of-schemas standard) + +This schema defines the structure of Unix-style manual pages written in Markdown. **Key Features:** - Validates H1 title format: `command(section) - description` @@ -58,63 +63,68 @@ A comprehensive manual page (section 7) documenting MarkiTect's markdown schema ## Running the Example -### 1. Validate the Manual Against the Schema +### 1. List Available Schemas -Verify that the manual conforms to the manpage schema: +View all registered schemas (including the manpage schema): + +```bash +markitect schema-list +``` + +You should see `manpage-schema-v1.0.md` listed with a number. + +### 2. Validate the Manual Against the Schema + +Verify that the manual conforms to the manpage schema using the new multi-schema validation: ```bash cd examples/manpages +# Validate by schema filename (from registry) +markitect schema-validate manpage-schema-v1.0.md + +# Or validate by number (if schema is #2 in the list) +markitect schema-validate 2 + +# Or validate a specific document file markitect validate markdown-schema-validation.1.md \ - --schema markdown-manpage-schema.json + --schema manpage-schema-v1.0.md ``` Expected output: ✅ **VALID** - Document structure matches schema requirements -### 2. Show Detailed Validation +### 3. Show Detailed Validation See detailed validation information: ```bash -markitect validate markdown-schema-validation.1.md \ - --schema markdown-manpage-schema.json \ - --detailed-errors +markitect schema-validate manpage-schema-v1.0.md --detailed-errors ``` -### 3. Generate Schema from the Manual +### 4. Validate Multiple Schemas -Analyze the manual's actual structure: +Validate all registered schemas at once: ```bash -markitect schema-generate markdown-schema-validation.1.md \ - --output actual-structure-schema.json +# Validate all schemas +markitect schema-validate --all -cat actual-structure-schema.json +# Validate a range of schemas +markitect schema-validate 1-3 + +# Validate specific schemas +markitect schema-validate 1,3,5 ``` -Compare the generated schema with the manpage schema to see how the manual conforms. +### 5. Examine the Schema -### 4. Examine AST Structure - -View the parsed structure of the manual: +View the manpage schema in markdown format: ```bash -markitect ast-show markdown-schema-validation.1.md --format tree -``` +markitect schema-get manpage-schema-v1.0.md -Or in compact format: - -```bash -markitect ast-show markdown-schema-validation.1.md --format compact | head -50 -``` - -### 5. Store Schema for Reuse - -Add the manpage schema to MarkiTect's database: - -```bash -markitect schema-ingest markdown-manpage-schema.json -markitect schema-list +# Or view the file directly +cat ../../markitect/schemas/manpage-schema-v1.0.md ``` ### 6. Validate Other Manpages @@ -122,22 +132,9 @@ markitect schema-list Use the schema to validate other manual pages in the project: ```bash +# Validate using schema name from registry markitect validate ../../docs/manuals/markitect.1.md \ - --schema markdown-manpage-schema.json - -markitect validate ../../docs/manuals/issue.1.md \ - --schema markdown-manpage-schema.json -``` - -### 7. Generate Manpage Template - -Create a template for new manpages: - -```bash -markitect generate-stub markdown-manpage-schema.json \ - --output new-manpage-template.md - -cat new-manpage-template.md + --schema manpage-schema-v1.0.md ``` ## What This Example Demonstrates @@ -246,7 +243,7 @@ Add to `.github/workflows/docs.yml` or similar: run: | for manpage in docs/manuals/*.md; do markitect validate "$manpage" \ - --schema examples/manpages/markdown-manpage-schema.json \ + --schema manpage-schema-v1.0.md \ || exit 1 done ``` @@ -261,11 +258,11 @@ changed_manpages=$(git diff --cached --name-only --diff-filter=ACM | grep 'docs/ for manpage in $changed_manpages; do markitect validate "$manpage" \ - --schema examples/manpages/markdown-manpage-schema.json \ + --schema manpage-schema-v1.0.md \ --quiet || { echo "Manpage validation failed: $manpage" markitect validate "$manpage" \ - --schema examples/manpages/markdown-manpage-schema.json \ + --schema manpage-schema-v1.0.md \ --detailed-errors exit 1 } @@ -282,7 +279,7 @@ validate-manpages: @echo "Validating manual pages..." @for manpage in docs/manuals/*.md; do \ markitect validate "$$manpage" \ - --schema examples/manpages/markdown-manpage-schema.json \ + --schema manpage-schema-v1.0.md \ || exit 1; \ done @echo "✅ All manpages valid" @@ -326,15 +323,17 @@ Create specialized schemas for different manpage types: ```bash # For command manpages (section 1) -cp markdown-manpage-schema.json command-manpage-schema.json +cp markitect/schemas/manpage-schema-v1.0.md command-manpage-schema-v1.0.md # Edit to require COMMANDS section +markitect schema-validate ./command-manpage-schema-v1.0.md +markitect schema-ingest ./command-manpage-schema-v1.0.md # For format manpages (section 5) -cp markdown-manpage-schema.json format-manpage-schema.json +cp markitect/schemas/manpage-schema-v1.0.md format-manpage-schema-v1.0.md # Edit to require FORMAT section # For convention manpages (section 7) -cp markdown-manpage-schema.json convention-manpage-schema.json +cp markitect/schemas/manpage-schema-v1.0.md convention-manpage-schema-v1.0.md # Edit to be more flexible ``` @@ -343,9 +342,9 @@ cp markdown-manpage-schema.json convention-manpage-schema.json Apply the manpage schema to your project: ```bash -# Validate README +# Validate README (if it follows manpage structure) markitect validate README.md \ - --schema markdown-manpage-schema.json + --schema manpage-schema-v1.0.md # May need adjustments for non-manpage docs ``` diff --git a/examples/terminology/README.md b/examples/terminology/README.md index f5d5679d..74a29b12 100644 --- a/examples/terminology/README.md +++ b/examples/terminology/README.md @@ -13,9 +13,11 @@ Terminology documents (glossaries, dictionaries, lexicons) benefit from consiste ## Files - **terminology-example.md** - Example terminology document with proper structure -- **terminology-schema.json** - JSON schema for validating terminology documents +- **Schema**: `terminology-schema-v1.0.md` (in `markitect/schemas/`) - **README.md** - This file +The terminology schema now follows the schema-of-schemas standard with markdown format and embedded JSON. + ## Terminology Document Structure A well-structured terminology document includes: @@ -51,39 +53,65 @@ Each term should include: ## Usage -### Using the Registered Schema +### List Available Schemas -The terminology schema is registered in markitect's database and can be used by name: +View all registered schemas (including terminology schema): ```bash -# List all registered schemas (terminology-schema.json should appear) markitect schema-list +``` -# Validate using the registered schema -markitect validate my-glossary.md --schema terminology-schema.json +You should see `terminology-schema-v1.0.md` listed with a number. -# Or use the local file directly -markitect validate my-glossary.md --schema examples/terminology/terminology-schema.json +### Validate Using the Schema + +The terminology schema is registered in MarkiTect's database. You can validate using multiple methods: + +```bash +# By schema number (if terminology schema is #4 in the list) +markitect schema-validate 4 + +# By schema filename (from registry) +markitect schema-validate terminology-schema-v1.0.md + +# Validate a specific document file +markitect validate my-glossary.md --schema terminology-schema-v1.0.md + +# Or use the local file path directly +markitect validate my-glossary.md --schema ./markitect/schemas/terminology-schema-v1.0.md ``` ### Validate with Detailed Errors ```bash -markitect validate my-glossary.md --schema terminology-schema.json --detailed-errors +markitect schema-validate terminology-schema-v1.0.md --detailed-errors ``` -### Register the Schema (if needed) +### Batch Validation -If the schema isn't already registered, you can add it to markitect's database: +Validate multiple schemas at once: ```bash -markitect schema-ingest markitect/schemas/terminology-schema.json +# Validate all schemas +markitect schema-validate --all + +# Validate a range +markitect schema-validate 1-4 + +# Validate specific schemas +markitect schema-validate 2,4 ``` -### Generate Schema from Example +### View the Schema + +Examine the terminology schema: ```bash -markitect schema-generate terminology-example.md --output my-terminology-schema.json +# Get from registry +markitect schema-get terminology-schema-v1.0.md + +# Or view the markdown file directly +cat markitect/schemas/terminology-schema-v1.0.md ``` ## Schema Features @@ -238,7 +266,7 @@ Include specialized validation rules: ```bash #!/bin/bash # .git/hooks/pre-commit -markitect validate docs/glossary.md --schema schemas/terminology-schema.json +markitect validate docs/glossary.md --schema terminology-schema-v1.0.md ``` ### GitHub Actions @@ -257,7 +285,7 @@ jobs: - name: Validate Glossary run: | markitect validate docs/glossary.md \ - --schema schemas/terminology-schema.json \ + --schema terminology-schema-v1.0.md \ --detailed-errors ```