✨ Add sd_custom_roles: config-defined badge roles with baked tooltips

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- ✨ NEW: `sd_custom_roles` defines reusable badge roles in `conf.py`,
+  inheriting a built-in badge role (`bdg`, `bdg-<color>`, `bdg-*-line`,
+  `bdg-link-*`, `bdg-ref-*`) and optionally baking in a default `tooltip` — the
+  recommended way to declare repeated status badges (`stable`/`beta`/...) once,
+  instead of retyping the `` ; tooltip `` suffix at every use site (a
+  per-instance suffix still overrides the baked default). A companion to
+  `sd_custom_directives`, fully TOML-representable; the roles are reconciled on
+  each build, so config edits are picked up and a removed role is unregistered,
+  and a name clashing with a docutils built-in or another extension's role is
+  skipped with a warning ({pr}`295`, {issue}`81`).
 - ♻️ IMPROVE: Replace the Sass/Node build with a dependency-free Python CSS
   generator (`tools/generate_css.py` driven by `style/design.toml` and
   hand-authored `style/*.css`); `package.json` is gone. The compiled

docs/badges_buttons.md

@@ -53,11 +53,83 @@ The syntax is the same as for the `ref` role.
 ````
 `````
 
+(sd-custom-badge-roles)=
+
+### Custom badge roles
+
+When the **same** badge recurs throughout your documentation — status labels
+such as *stable*, *beta* or *deprecated* whose colour and tooltip never change —
+define it **once** as a custom role via the `sd_custom_roles` configuration
+option, rather than retyping the colour and tooltip at every use site. This is
+the recommended pattern for such repeated, semantic badges:
+
+```python
+sd_custom_roles = {
+    "bdg-stable": {
+        "inherit": "bdg-success",
+        "tooltip": "A released, supported version",
+    },
+    "bdg-beta": {"inherit": "bdg-warning", "tooltip": "Interface may change"},
+    "bdg-deprecated": {"inherit": "bdg-danger", "tooltip": "Scheduled for removal"},
+}
+```
+
+Each key is the new role name to register; the value is a dictionary with:
+
+- `inherit` (required): the built-in badge role to inherit from — any of the
+  `bdg`, `bdg-<color>`, `bdg-<color>-line`, `bdg-link-*` or `bdg-ref-*` roles.
+- `tooltip` (optional): a default tooltip, applied as the HTML `title` whenever
+  the role is used *without* a per-instance `; tooltip` suffix. For a
+  `bdg-link-*`/`bdg-ref-*` role the baked tooltip applies even to the bare
+  form (`` {bdg-link-*}`<target>` ``), where the suffix grammar deliberately
+  refuses to split, and it overrides a reference's automatic title.
+
+Give custom roles a distinguishing prefix (the `bdg-` convention used here is a
+good choice): a name that collides with a docutils built-in (`code`, `math`,
+`strong`, …) or another extension's role is skipped, so `bdg-`-prefixed names
+keep you clear of every such clash.
+
+The new role then behaves exactly like the role it inherits (same rendering,
+links and references), with its tooltip baked in:
+
+{bdg-stable}`v2.1` {bdg-beta}`v3.0rc1` {bdg-deprecated}`v1.0`
+
+````{tab-set-code}
+```markdown
+{bdg-stable}`v2.1` {bdg-beta}`v3.0rc1` {bdg-deprecated}`v1.0`
+```
+```rst
+:bdg-stable:`v2.1` :bdg-beta:`v3.0rc1` :bdg-deprecated:`v1.0`
+```
+````
+
+A baked `tooltip` is only the *default*: a per-instance `; tooltip` suffix on an
+individual badge **overrides** it, so a config-defined role covers the common
+case while the suffix stays available for the occasional one-off:
+
+{bdg-stable}`v2.1 ; Long-term support release`
+
+````{tab-set-code}
+```markdown
+{bdg-stable}`v2.1 ; Long-term support release`
+```
+```rst
+:bdg-stable:`v2.1 ; Long-term support release`
+```
+````
+
+Custom roles are the badge analogue of
+{ref}`custom directives <sd-custom-directives>`. Inheritance is limited to the
+badge family listed above; a role whose `inherit` names an unknown badge role,
+or whose own name clashes with an existing role, is skipped with a warning.
+Editing an entry (or removing it) is picked up on the next build.
+
 ### Badge tooltips
 
-Any badge can be given a tooltip (shown on hover, via the HTML `title`
-attribute) by appending a `; tooltip` suffix to its text.
-This works for every badge family:
+For a **one-off** tooltip (shown on hover, via the HTML `title` attribute) —
+rather than a repeated one better served by a
+{ref}`custom badge role <sd-custom-badge-roles>` — append a `; tooltip` suffix
+to any badge's text. This works for every badge family:
 
 {bdg-primary}`stable ; A released, supported version`
 {bdg-link-info}`docs <https://example.com> ; Opens the documentation`

docs/conf.py

@@ -41,6 +41,14 @@
         },
     }
 }
+sd_custom_roles = {
+    "bdg-stable": {
+        "inherit": "bdg-success",
+        "tooltip": "A released, supported version",
+    },
+    "bdg-beta": {"inherit": "bdg-warning", "tooltip": "Interface may change"},
+    "bdg-deprecated": {"inherit": "bdg-danger", "tooltip": "Scheduled for removal"},
+}
 
 extlinks = {
     "pr": ("https://github.com/executablebooks/sphinx-design/pull/%s", "PR #%s"),

docs/get_started.md

@@ -60,6 +60,8 @@ sd_hide_title: true
 :::
 ::::
 
+(sd-custom-directives)=
+
 ### Creating custom directives
 
 :::{versionadded} 0.6.0
@@ -86,6 +88,10 @@ The key is the new directive name to add, and the value is a dictionary with the
 - `argument`: The default argument (optional, only for directives that take a single argument)
 - `options`: A dictionary of default options for the directive (optional)
 
+The same idea is available for roles: `sd_custom_roles` defines reusable badge
+roles (e.g. status badges), inheriting a built-in badge role and optionally
+baking in a tooltip. See {ref}`Custom badge roles <sd-custom-badge-roles>`.
+
 ## Supported browsers
 
 sphinx-design targets [**Baseline** Widely Available](https://web.dev/baseline)