# Version Directives

URL: /docs/content/versioning/directives/
Section: versioning

--------------------------------------------------------------------------------

Version Directives Bengal provides three directives for marking version-specific content: Directive Purpose Rendered As :::{since} Feature added in version X New in X :::{deprecated} Feature deprecated in version X Deprecated since X :::{changed} Behavior changed in version X Changed in X Each directive renders with an SVG icon and themed styling using CSS classes. Since Directive Marks content that was added in a specific version. Syntax :::{since} v2.0 This feature was added in version 2.0. ::: Rendered Output New in v2.0 This feature was added in version 2.0. Use Cases Document new features: ## Webhooks :::{since} v2.5 Webhooks allow you to receive real-time notifications when events occur. ::: To configure webhooks: 1. Go to Settings → Webhooks 2. Add your endpoint URL 3. Select events to subscribe to Mark new parameters: ### Parameters | Name | Type | Description | |------|------|-------------| | `timeout` | `int` | Request timeout in seconds | | `retries` | `int` | Number of retries :::{since} v2.1 ::: | Deprecated Directive Marks content that is deprecated and will be removed in a future version. Syntax :::{deprecated} v3.0 Use `new_function()` instead. This will be removed in v4.0. ::: Rendered Output Deprecated since v3.0 Use new_function() instead. This will be removed in v4.0. Use Cases Deprecate a function: ## old_function() :::{deprecated} v3.0 This function is deprecated. Use [[docs/api#new-function|new_function()]] instead. ::: ```python # Don't use this result = old_function(data) # Use this instead result = new_function(data) ``` Deprecate a configuration option: ### legacy_mode :::{deprecated} v2.5 The `legacy_mode` option is deprecated and will be removed in v3.0. Migrate to the new configuration format. ::: ```yaml # Deprecated legacy_mode: true # New approach compatibility: version: 2 ``` Changed Directive Marks content where behavior changed in a specific version. Syntax :::{changed} v2.5 Default timeout changed from 30 seconds to 60 seconds. ::: Rendered Output Changed in v2.5 Default timeout changed from 30 seconds to 60 seconds. Use Cases Document behavior changes: ## Configuration ### timeout The request timeout in seconds. :::{changed} v2.5 Default changed from 30 to 60 seconds for better reliability with slow networks. ::: **Default:** 60 seconds Document API changes: ## Response Format :::{changed} v3.0 The response now includes a `metadata` field with additional information. ::: ```json { "data": [...], "metadata": { // New in v3.0 "total": 100, "page": 1 } } ``` Inline Usage All directives can be used inline for brief annotations: | Option | Default | Description | |--------|---------|-------------| | `timeout` | 60s | Request timeout :::{changed} v2.5 was 30s ::: | | `retries` | 3 | Retry count :::{since} v2.0 ::: | | `legacy` | false | Legacy mode :::{deprecated} v3.0 ::: | Without Version Number The deprecated and changed directives support omitting the version number for generic notices: :::{deprecated} This feature is deprecated. ::: :::{changed} This behavior has changed. ::: Note Note The since directive requires a version number. Without one, no output is rendered. Styling Each directive renders with an inline SVG icon and themed styling. The directives use CSS classes you can customize: /* Since directive - success/green theme */ .version-since { --version-color: var(--color-success); background-color: var(--color-success-bg); } /* Deprecated directive - warning/orange theme */ .version-deprecated { --version-color: var(--color-warning); background-color: var(--color-warning-bg); } /* Changed directive - info/blue theme */ .version-changed { --version-color: var(--color-info); background-color: var(--color-info-bg); } Badges include Lucide-style SVG icons (.version-badge-icon) that inherit the theme color via currentColor. Full directive containers (when content is provided) feature a luminescent glow animation and neumorphic styling. Combining Directives You can combine directives for comprehensive version history: ## process_data() :::{since} v1.0 Core data processing function. ::: :::{changed} v2.0 Added support for streaming data. ::: :::{changed} v2.5 Default batch size increased from 100 to 1000. ::: Processes data with automatic batching and retry logic. Best Practices Be Specific ❌ Vague: :::{changed} v2.0 This was changed. ::: ✅ Specific: :::{changed} v2.0 Return type changed from `list` to `iterator` for memory efficiency. ::: Include Migration Path For deprecations, always explain what to use instead: :::{deprecated} v3.0 Use `new_api()` instead. See the [[docs/migration|migration guide]] for details. ::: Don't Overuse Version directives are most valuable for: Breaking changes New major features Deprecations Don't annotate every minor change—it creates noise. Next Steps Cross-Version Links — Link between versions Folder Mode — Set up folder-based versioning Git Mode — Set up git-based versioning

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 709
- Reading Time: 4 minutes