# Versioning Directives URL: /docs/reference/directives/versioning/ Section: directives -------------------------------------------------------------------------------- Versioning Directives Mark content as added, changed, or deprecated in specific versions. Use these directives to help users understand API evolution and migration paths. Quick Reference Directive Alias Purpose Theme Color :::{since} {versionadded} New feature/API Success (green) :::{deprecated} {versionremoved} Deprecated feature Warning (orange) :::{changed} {versionchanged} Behavior change Info (blue) since Marks content that was added in a specific version. Alias: {versionadded} Syntax :::{since} v2.0 This feature was added in version 2.0. ::: Options Option Type Description (argument) string Required. Version identifier (e.g., v2.0, 2.0, 2024.1) :class: string Additional CSS class (default: version-since) Examples Example: Basic Usage :::{since} v2.0 Webhooks allow real-time event notifications. ::: Example: Inline Badge (No Content) :::{since} v2.0 ::: Example: Inline in Tables | Option | Description | |--------|-------------| | `retries` | Retry count :::{since} v3.1 ::: | Rendered Output Inline badge (no content): Neumorphic badge with subtle shadow SVG sparkles icon Success/green theme colors Full directive (with content): Left-edge accent border with palette-aware colors Subtle background blob animation Rounded container with badge header deprecated Marks content that is deprecated and will be removed. Alias: {versionremoved} Syntax :::{deprecated} v3.0 Use `new_function()` instead. ::: Options Option Type Description (argument) string Version when deprecated. If omitted, displays "Deprecated" without version. :class: string Additional CSS class (default: version-deprecated) Examples Example: Basic Usage :::{deprecated} v3.0 This function is deprecated. Use `new_api()` instead. ::: Example: With Migration Path :::{deprecated} v3.0 The `legacy_mode` option is deprecated. **Migration:** 1. Remove `legacy_mode: true` from config 2. Add `compatibility.version: 2` See [[docs/migration|migration guide]] for details. ::: Example: Without Version :::{deprecated} This feature is deprecated and will be removed. ::: Rendered Output Inline badge (no content): Neumorphic badge with subtle shadow SVG alert triangle icon Warning/orange theme colors Full directive (with content): Left-edge accent border with palette-aware colors Subtle background blob animation (warning colors) Rounded container with badge header changed Marks content where behavior changed in a specific version. Alias: {versionchanged} Syntax :::{changed} v2.5 Default timeout changed from 30s to 60s. ::: Options Option Type Description (argument) string Version when changed. If omitted, displays "Changed" without version. :class: string Additional CSS class (default: version-changed) Examples Example: Basic Usage :::{changed} v2.5 The default batch size increased from 100 to 1000. ::: Example: API Response Change :::{changed} v3.0 Response now includes a `metadata` field: ```json { "data": [...], "metadata": { "total": 100, "page": 1 } } ::: :::{example-label} Without Version ::: ```markdown :::{changed} This behavior has been updated. ::: Rendered Output Inline badge (no content): Neumorphic badge with subtle shadow SVG refresh icon Info/blue theme colors Full directive (with content): Left-edge accent border with palette-aware colors Subtle background blob animation (info colors) Rounded container with badge header CSS Classes All versioning directives use consistent CSS classes that integrate with Bengal's theme system: /* Container classes - full directive with content */ .version-directive { } /* Base container with glow animation */ .version-directive-header { } /* Badge container */ .version-directive-content { } /* Content wrapper */ /* Type-specific containers */ .version-since { } /* Success/green theme */ .version-deprecated { } /* Warning/orange theme */ .version-changed { } /* Info/blue theme */ /* Badge classes - inline badges */ .version-badge { } /* Base neumorphic badge */ .version-badge-since { } /* New in X.X badge */ .version-badge-deprecated { } /* Deprecated badge */ .version-badge-changed { } /* Changed badge */ .version-badge-icon { } /* SVG icon styling */ Customizing Styles Version directives use CSS custom properties for easy theming: /* Override colors for custom themes */ .version-since { --version-color: var(--color-success); } .version-deprecated { --version-color: var(--color-warning); } .version-changed { --version-color: var(--color-info); } Animation respects prefers-reduced-motion. For complete customization, see assets/css/components/versioning.css in the default theme. Best Practices Be Specific Include details about what changed: <!-- ❌ Vague --> :::{changed} v2.0 This was updated. ::: <!-- ✅ Specific --> :::{changed} v2.0 Return type changed from `list[dict]` to `Iterator[dict]` for improved memory efficiency with large datasets. ::: Include Migration Paths For deprecations, explain the alternative: :::{deprecated} v3.0 `old_function()` is deprecated. **Use instead:** ```python from mylib import new_function result = new_function(data) See [docs/api] for details. ::: ### Use Sparingly Version directives are most valuable for: - ✅ Breaking changes - ✅ Major new features - ✅ Deprecations with removal timeline - ✅ Significant behavior changes Avoid for: - ❌ Minor bug fixes - ❌ Internal changes - ❌ Every small addition --- ## Related - [Versioning Documentation](/docs/content/versioning/) — Full versioning guide - [Cross-Version Links](/docs/content/versioning/cross-version-links/) — Link between versions - [Admonitions](/docs/reference/directives/admonitions/) — Standard callout directives -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 738 - Reading Time: 4 minutes