Schemars 1.2.0 changed how HashMap<EnumKey, T> generates schemas.
Instead of using additionalProperties with a schema, it now generates
explicit properties with enum variant names as keys and
additionalProperties: false.
This change:
- Updates get_map_inner_type to detect both schemars 1.1 and 1.2 patterns
- Adds is_enum_keyed_map helper to identify enum-keyed map schemas
- Fixes usage link generation to skip enum-keyed map properties
(they render inline without heading anchors)
- Maintains backward compatibility with schemars 1.1 schemas
Fixes wrapper type detection so PerAnimationPrefixConfig displays
instead of PerAnimationPrefixConfig2/3, and prevents broken anchor
links to non-existent property headings.
For Pattern 6 (Internally Tagged + Flatten) enum variants that have both
`type: "object"` and `$ref` at the same level, the Value line now shows
a link to the referenced type instead of displaying "object".
Before:
#### Catppuccin
Theme from catppuccin-egui
**Value:** `object`
#### name
...all properties from KomorebiThemeCatppuccin inlined...
After:
#### Catppuccin
Theme from catppuccin-egui
**Value:** [`KomorebiThemeCatppuccin`](#komorebithemecatppuccin)
Changes:
- Move $ref check to top of render_type_badge macro, prioritizing it
over type when both are present
- Remove property inlining for Pattern 6 variants with $ref since the
link makes inlined properties redundant
- Add test assertions verifying $ref link display and no property
inlining for Pattern 6 variants
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 new --format mdx option to generate Astro Starlight-compatible
MDX documentation from JSON Schema.
Features:
- New MdxGenerator with Tera templates (mdx_base.md, mdx_macros.md)
- Custom heading IDs using {#anchor} syntax for reliable deep linking
- Starlight Badge components for required/optional/deprecated markers
- MDX escape filter for curly braces in descriptions
- Reuses existing schema preparation from prepare.rs
Changes:
- src/mdx_generator.rs: New MDX generation module
- src/templates/mdx_base.md: Base MDX template with frontmatter
- src/templates/mdx_macros.md: Tera macros for MDX rendering
- src/lib.rs: Add generate_mdx() public API and MdxOptions
- src/main.rs: Add --format argument (html/mdx)
- src/prepare.rs: Fix oneOf variant usage anchors for bare $ref
The MDX output integrates with Starlight's TOC generation via
remark-custom-heading-id plugin and produces valid MDX that passes
mdxlint validation.
Previously, add_wrapper_display_names() would add a _display_name field
to ALL types with trailing digits, incorrectly affecting legitimate type
names like Base16, Sha256, or Level3.
Now the function only strips trailing digits from types that are marked
as wrapper types (_wrapper_type: true), leaving other type names intact.
Adds comprehensive tests for both cases:
- Legitimate type names ending in digits remain unchanged
- Wrapper type variants (e.g., PerAnimationPrefixConfig2) get proper
_display_name fields with digits stripped
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.
Add extensive CSS media queries and overflow handling for proper mobile
device display of generated documentation.
Overflow Prevention:
- Set `overflow-x: hidden` on body and main-content
- Add `word-break: break-word` and `overflow-wrap: anywhere` to property names
- Enable horizontal scrolling inside pre blocks and enum values
- Ensure code elements break properly on narrow screens
Mobile Layout Adjustments (148 lines):
- Reduce padding throughout (main-content, definition, description, usages)
- Smaller font sizes for headers, titles, and definition names
- Adjust modal sizing: full width, 90vh max height, reduced padding
- Compact nested schema containers (properties, array-items, variants)
Search Results Mobile:
- Flex-wrap enabled for search result items
- Result path takes full width with word breaking
- Reorder elements with CSS order property
Typography Scaling:
- Header h1: 1.25rem
- Schema section h2: 1.25rem
- Definition names: 1.1rem with word-break
- Modal title: 1rem
Component Spacing:
- Reduced gap in property-header
- Smaller margins on type badges and refs
- Compact constraints display (flex-direction: column)
- Reduced padding on nested-schema summaries
Implement a modal popup system for viewing type definitions without leaving
the current context, with browser-like back/forward navigation.
Modal UI Components:
- Full-screen overlay with centered modal dialog
- Header with title, close button, and navigation controls
- Scrollable content area for type definition
- Back (←) and forward (→) navigation buttons
- Visual disabled state for navigation at history bounds
Navigation Features:
- Click any type reference in root schema to open in modal
- Click type references within modal to navigate deeper
- Keyboard shortcuts: Alt+← (back), Alt+→ (forward), Escape (close)
- History tracking with array and index pointer
- History resets on modal close
JavaScript Implementation:
- `openTypeModal(typeName, addToHistory)`: Open/navigate to type
- `showType(typeName)`: Clone and display type definition content
- `navigateHistory(direction)`: Handle back/forward navigation
- `closeModal()`: Close modal and reset state
- `updateNavButtons()`: Enable/disable nav buttons based on position
CSS Styling (102 lines added):
- `.modal-overlay`: Fixed positioning with semi-transparent background
- `.modal`: Centered container with max dimensions and shadow
- `.modal-header`: Flex layout for nav, title, and close button
- `.modal-nav-btn`: Styled navigation buttons with disabled state
- `.modal-content`: Scrollable content with padding
Identifier Updates:
- Add modal-related IDs and classes to identifiers.rs
- New ID: `modal-overlay`
- New classes: modal, modal-active, modal-header, modal-title, modal-close,
modal-content, modal-nav, modal-nav-btn, disabled
Fix template rendering for tuples (arrays with prefixItems) that contain
non-primitive types like $ref or anyOf, which were incorrectly detected
as homogeneous tuples.
Template Logic Fix:
- Check if `item.type` and `first_type.type` are both defined before comparing
- Treat items with $ref, anyOf, or missing type as heterogeneous
- Apply fix in all three locations: render_type_badge, render_array_items_inline,
and render_array_items macros
Display Name Enhancement:
- Strip trailing digits from ALL type names, not just wrapper types
- Types like `DisplayFormat2` now display as `DisplayFormat`
- Only adds `_display_name` when it differs from original name
Create a single source of truth for all CSS class names and HTML element IDs
used throughout the generated documentation.
New Module (`src/identifiers.rs`):
- `HtmlIds` struct: Static HTML IDs for JS interaction (search, sidebar, etc.)
- `CssClasses` struct: All CSS class names organized by category
- `TypeClasses` struct: Type-specific badge classes (type-string, type-integer, etc.)
- Constants `IDS`, `CSS`, `TYPE_CLASSES` for compile-time access
- Serializable via serde for use in Tera templates
Class Categories:
- Layout: header, layout, main-content
- Sidebar: sidebar, sidebar-open, sidebar-toggle, sidebar-section
- Navigation: nav-list, nav-link, outline-list, outline-item
- Search: search-container, search-results, search-result-item
- Schema: schema-section, properties-container, property, property-header
- Badges: badge, required, deprecated, optional
- Types: type-badge, type-ref, and all type-specific classes
- Nested: nested-schema, array-items, tuple-items, variants
- Definition: definition, definition-name, highlight, usages
Template Updates:
- Replace hardcoded class strings with `{{ css.class_name }}` references
- Replace hardcoded IDs with `{{ ids.id_name }}` references
- Enables IDE navigation and refactoring support
Also adds `schema.json` test fixture (komorebi configuration schema)
Fix visual spacing issues between type badges, references, and other inline
elements in the generated documentation.
CSS Changes:
- Add `margin-left: 0.25rem` to `.badge`, `.type-badge`, and `.type-ref`
- Add `:first-child` selectors to remove left margin on first elements
- Ensures consistent spacing when multiple badges appear together
Template Fixes:
- Remove excess whitespace in Tera template conditionals
- Fix spacing around optional badges and type badges in `render_type_badge`
- Consolidate inline spacing in `render_schema` macro
- Clean up wrapper type inner badge rendering whitespace
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)
LGUG2Z