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

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

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

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

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 respectsprefers-reduced-motion. For complete customization, seeassets/css/components/versioning.cssin 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