BREAKING CHANGE: HTML output format has been removed. The tool now
generates MDX documentation for Astro Starlight exclusively.
This commit removes the HTML generator and all associated code,
simplifying the codebase to focus on MDX output only.
Removed
- `src/generator.rs` - HTML documentation generator (1827 lines)
- `src/identifiers.rs` - CSS/HTML identifiers (371 lines)
- `src/templates/base.html` - HTML base template
- `src/templates/macros.html` - HTML macro templates
- `src/templates/style.css` - CSS styles (1216 lines)
- `src/templates/test_index.html` - Test HTML template
- `build.rs` - CSS minification build script
- `tests/json_schema_test_suite.rs` - JSON Schema test suite (501 lines)
- `tests/fixtures/json-schema-test-suite/` - All draft2020-12 test fixtures
Removed Dependencies
- lightningcss (CSS minification)
- rayon (parallel processing)
- struct_iterable (struct iteration)
- regex, chrono (dev dependencies)
Added
- `ENUMS.md` - Comprehensive documentation of all 11 Rust enum patterns
and their JSONSchema representations
- 12 unit tests covering all enum patterns to prevent Value duplication
Changed
CLI (src/main.rs)
- Remove `--format` flag (was html/mdx, now mdx only)
- Remove `Format` enum
- Simplify to always output MDX
Library (src/lib.rs)
- Remove `Options` struct and `generate_html()` function
- Remove `Generator`, `CSS`, `IDS`, `TYPE_CLASSES` exports
- Update module docs to reflect MDX-only output
- Update tests to use `generate_mdx()`
Templates (src/templates/mdx_macros.md)
- Add section headers organizing macros by function
- Add comprehensive comments documenting all enum patterns
- Fix duplicate Value rendering for const variants
- Add Pattern 7 detection for externally tagged enums
- Change `<details>` to `<details open>` for better visibility
- Render required properties before optional ones
- Move `$ref` handling after `type` in render_type_badge (Pattern 6 fix)
Preparation (src/prepare.rs)
- Minor formatting improvements
- Add default value linking: when a default value refers to an enum
variant, it now links to the type definition (e.g., "Monitor" links
to CrossBoundaryBehaviour type)
- Make mdx_escape code-block aware: braces inside fenced code blocks
(```) and inline code (`) are no longer escaped, preserving proper
JSON code block rendering in descriptions
- Use raw markdown descriptions in MDX templates instead of converting
to HTML then stripping tags, which was destroying code blocks
- Skip redundant type badge for documented const variants in MDX output
Add functionality to generate an index.html file after running the
JSON Schema Test Suite integration tests, providing easy navigation
of generated documentation.
Features:
- Use Tera template (test_index.html) for consistent styling
- Display statistics: total schemas, test files, with/without content
- Annotate each schema with content status (has properties/$defs or not)
- Show JSON Schema features/keywords used in each test schema
- Include build information: git commit hash, dirty status, timestamps
- Group schemas by source test file for easy navigation
Add comprehensive integration tests using the official JSON-Schema-Test-Suite
draft2020-12 examples to ensure the CLI handles all valid JSON Schema constructs
without crashing.
Changes:
- Add 80 fixture files from JSON-Schema-Test-Suite draft2020-12
- Add parallelized integration test that runs CLI against all 448 schemas
- Normalize non-standard $ref patterns (root refs, JSON pointers, external URIs)
- Decode URL-encoded and JSON pointer escaped characters in $ref paths
- Embed type usages directly in $defs to avoid Tera lookup issues with
special characters in definition names
- Handle missing $defs gracefully in template rendering
The test suite runs in ~5 seconds using Rayon for parallel execution.
Implement compile-time validation that all CSS class names defined in
identifiers.rs have corresponding styles in style.css.
Build Script Integration:
- Add build.rs with lightningcss for CSS parsing
- Parse style.css and extract all class selectors
- Iterate over CssClasses and TypeClasses using struct_iterable
- Fail build if any defined class lacks CSS rules
Runtime Test (backup validation):
- Add `test_all_css_classes_are_styled` in identifiers.rs
- Uses regex to extract class names from CSS file
- Verifies both CSS and TYPE_CLASSES are fully styled
- Allows dynamic prefixes like "depth-" that are generated at runtime
Struct Changes:
- Add `#[derive(Iterable)]` to CssClasses and TypeClasses
- Add `#[allow(dead_code)]` to IDS and HtmlIds (used by main, not build)
Cleanup:
- Remove unused CSS classes: `map_entries`, `too_deep`
- Remove corresponding entries from identifiers.rs
New Dependencies:
- lightningcss = "1.0.0-alpha.68" (build-dependency)
- struct_iterable = "0.1" (dependency and build-dependency)
- serde with derive (build-dependency for struct_iterable)
This ensures CSS/Rust synchronization is maintained and catches
missing styles before runtime.
Implement intelligent detection of "wrapper types" (anyOf patterns with map
variant and inner type) to render them more meaningfully in documentation.
Wrapper Type Detection:
- Detect anyOf patterns like `[{object with additionalProperties: T}, T]`
- Mark detected wrappers with `_wrapper_type` and `_wrapper_inner` metadata
- Display inner type directly instead of showing misleading "enum" badge
- Link wrapper types to their inner type definitions
- Add `_display_name` field for wrapper types with numeric suffixes
Float Display Improvements:
- Display "float" instead of "number" for JSON Schema number types in tuples
- Use `type-float` CSS class for consistent styling
- Homogeneous tuples now show as "float; N" for number arrays
Navigation Enhancements:
- Build navigation from prepared schema (includes wrapper display names)
- Add `display_names` map to template context for type name resolution
- Track type usages for "Usages" section in definitions
Test Coverage:
- Add comprehensive tests for wrapper type rendering
- Test tuple float/integer display formatting
- Verify wrapper types don't show "Enum variants" dropdown
- Test non-wrapper anyOf still correctly shows enum badge
Implement a complete Rust library and CLI tool for generating self-contained
HTML documentation from schemars::Schema (JSON Schema) objects.
Core Features:
- Library API with `generate_html()` function and `Options` struct
- CLI binary accepting JSON Schema input files with optional title override
- Tera-based HTML templating with base template and reusable macros
- Markdown rendering for schema descriptions via pulldown-cmark
- Dark/light theme support following system preferences
- Searchable properties with instant search functionality
- Collapsible nested structures for complex schemas
- Responsive design for mobile, tablet, and desktop
Library Components:
- `generator.rs`: Main HTML generation logic with Tera template engine
- `prepare.rs`: Schema preprocessing for template rendering (1667 lines)
- `lib.rs`: Public API with SchemaExt trait for typed schema accessors
- `main.rs`: CLI interface using clap for argument parsing
Template System:
- `base.html`: Main HTML structure with header, sidebar, and content areas
- `macros.html`: Reusable Tera macros for rendering schema components
- `style.css`: Complete CSS with CSS variables for theming (955 lines)