Change Log

Unreleased

  • ♻️ 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 sphinx-design.min.css is a rule-set no-op apart from two deliberate changes. Hover/focus shades now use runtime color-mix() (behind a static fallback), so overriding a --sd-color-* variable now flows through to its -highlight shade instead of the shade being frozen at build time. Also purges ~150 dead vendor prefixes (IE -ms-flex*, and -moz-/-webkit- animation, box-sizing and user-select duplicates) that no supported browser needs. The migration was verified rule-for-rule and cascade-order-faithful against the previous stylesheet, and the new build fails loudly on unregistered style files, malformed token data, or a stale/unparsable artifact — see the new “Design: the CSS pipeline” documentation page (PR #290)

  • 📚 DOCS: Document the browser support policy as Baseline Widely Available (evergreen Chrome/Edge/Firefox/Safari, no Internet Explorer), replacing the stale 2021 Bootstrap browserslist mirror (PR #290)

  • 🔧 MAINTAIN: CI now compiles the documentation’s LaTeX output to PDF (exercising the sd_fontawesome_latex="fontawesome5" icon path, which the docs now use), and the fa-build hint recommends "fontawesome5" over the legacy FontAwesome 4 package (PR #289)

  • ✨ NEW: sd_fontawesome_version makes icon role names version-agnostic: any spelling (fas, fa-solid, …) can emit the FontAwesome "4", "5" or "6" class scheme, so upgrading FontAwesome is a one-line conf.py change; the default "as-named" keeps emitting the role name verbatim (PR #288, #174)

  • ✨ NEW: Badge roles accept a trailing ; tooltip suffix, rendered as a native HTML title tooltip on all bdg-* families; for the link/ref badges the suffix applies only after the explicit text <target> form (semicolons are valid in URLs and reference targets), and a literal ; in badge text is escaped as \; (PR #286, #81)

  • ✨ NEW: FontAwesome v6 roles (fa-solid/fa-brands/fa-regular) and declarative CSS loading via the new sd_fontawesome_source / sd_fontawesome_cdn_url options (the supported path for FontAwesome Pro kits) (PR #285, #174)

  • 👌 IMPROVE: sd_fontawesome_latex now also accepts "fontawesome5" (adding fontawesome5.sty and emitting \faIcon{...}), resolving package clashes with themes that load fontawesome5; True/False keep working unchanged (PR #285, #242)

  • 🐛 FIX: Synced tabs stay in sync when activated by click-and-drag or keyboard, by syncing on the radio input’s change event rather than a label click (PR #284, #46)

  • ✨ NEW: A URL fragment that targets a tab (e.g. page.html#tab-name), or an element inside a tab panel, now opens that tab (both on load and on hashchange) (PR #284, #239)

  • 👌 IMPROVE: Tab selections now persist across browsing sessions, via localStorage instead of sessionStorage (a behaviour change), and the storage key prefix is configurable with the new sd_tabs_storage_prefix option (set it to an empty string to disable persistence) (PR #284, #103)

  • 👌 IMPROVE: Restore keyboard focus rings on tab labels, dropdown summaries, buttons and stretched-link cards, using :focus-visible so they are visible for keyboard users but not shown on mouse click, thanks to @gabalafou in PR #230 (carried in PR #283)

  • 👌 IMPROVE: Each tab label now carries an aria-controls attribute referencing its content panel’s id, establishing the programmatic relationship in the accessibility tree (note: this is not a full WAI-ARIA tabs pattern; assistive-technology support for aria-controls varies) (PR #283, #30)

  • 🐛 FIX: card/grid-item-card :link: no longer strips whitespace from reference targets (and lowercases them for link-type: ref, matching the :ref: role), completing the fix for #110 (PR #282)

  • 🐛 FIX: button-ref no longer strips whitespace from reference targets, so multi-word labels (e.g. from autosectionlabel) resolve correctly (PR #281, #110)

  • 🐛 FIX: button-ref now renders rich/nested inline content (emphasis, icons, etc.) identically to button-link, instead of flattening it to plain text during cross-reference resolution (PR #281, #228)

  • 🐛 FIX: Inline icon roles no longer leak SVG markup into toctree labels and the search index (PR #279, #99)

  • 🐛 FIX: article-info octicons regain their sd-pr-2 spacing class (previously silently dropped by the HTML writer) (PR #279)

  • 🐛 FIX: Paragraphs inside dropdowns no longer have user classes overwritten by sd-card-text, and card/dropdown body styling is applied only to direct child paragraphs, not nested content (PR #278, #40)

  • ✨ NEW: sphinx_design.testing module with the normalize_doctree_xml helper, for downstream extensions’ doctree regression tests (PR #277, #260)

  • ♻️ IMPROVE: Static assets (CSS/JS) are now served via Sphinx’s standard html_static_path mechanism, rather than being written directly into the build output; non-HTML builds no longer gain a spurious _sphinx_design_static directory (PR #276, #200, #235). A stale _sphinx_design_static directory left in an existing HTML build directory by previous versions is unused and can safely be deleted.

  • ⬆️ UPGRADE: Sphinx >=7.2 is now required (PR #276)

  • 🗑️ REMOVE: The private sphinx_design._compat.findall helper has been removed (docutils Element.findall is guaranteed by the Sphinx floor); any code importing it should call node.findall(...) directly (PR #276)

  • 🐛 FIX: buttons are no longer destroyed by gettext translation: translated button-link/button-ref keep their styling and links (gettext now targets only the button text), thanks to @sneakers-the-rat in PR #264 (#96, #44, #263)

0.7.0 - 2025-01-19

Dependencies

Docs

0.6.1 - 2024-08-02

0.6.0 - 2024-05-23

Dependencies

New

✨ Create custom directives

You can use the sd_custom_directives configuration option in your conf.py to add custom directives, with default option values:

sd_custom_directives = {
  "dropdown-syntax": {
    "inherit": "dropdown",
    "argument": "Syntax",
    "options": {
      "color": "primary",
      "icon": "code",
    },
  }
}

The key is the new directive name to add, and the value is a dictionary with the following keys:

  • inherit: The directive to inherit from (e.g. dropdown)

  • argument: The default argument (optional, only for directives that take a single argument)

  • options: A dictionary of default options for the directive (optional)

by @chrisjsewell in PR #194

✨ sync tabs by URL query parameters

Synchronised tabs can now be selected by adding a query parameter to the URL, for that sync-group, such as ?code=python for

.. tab-set-code::

    .. literalinclude:: snippet.py
        :language: python

    .. literalinclude:: snippet.js
        :language: javascript

The last selected tab key, per group, is also persisted to SessionStorage

by @mikemckiernan and @chrisjsewell in PR #196

Improve

👌 Improve dropdown title bar

There are three visible changes:

  1. The “default” behaviour of the right chevron is to go from right-facing (closed) to down-facing (open), instead of down-facing (closed) to up-facing (open). There is also a rotate transition on opening/closing. The old default behaviour can be retained by using the new :chevron: down-up directive option.

  2. The prefix icon (optional), title text, and chevron state icon are now all better aligned

  3. The top/bottom padding is now 0.5em instead of 1em

The PR also introduces three new CSS variables to control font sizes of the dropdown:

--sd-fontsize-tabs-label: 1rem;
--sd-fontsize-dropdown-title: 1rem;
--sd-fontweight-dropdown-title: 700;

Internally, the HTML / CSS is changed, such that the title is now an inline-flex box, with three columns arranged with justify-content: space-between:

icon (optional)

text (flex-grow: 1)

state chevron

Also, the state chevron was previously two distinct SVGs (with one hidden), but now is one that get rotated on open/close.

by @chrisjsewell in PR #192

Fix

Internal

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.5.0…v0.6.0

0.5.0 - 2023-07-27

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.4.1…v0.5.0

v0.4.0 - 2023-04-13

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.3.0…v0.4.0

Enhancements made

Version upgrades

Contributors to this release

The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.

(GitHub contributors page for this release)

v0.3.0 - 2022-08-22

  • ⬆️ Update Materials Design Icons to v4.0.0-46-gc9e5528, thanks to @2bndy5 (PR #69)

  • 🐛 FIX: dropdown/tab-item :name: options (PR #91)

  • 🐛 FIX: Docs build against non-html formats (PR #88)

  • 👌 IMPROVE: Add card options class-img-top/class-img-bottom (PR #92)

  • 👌 IMPROVE: Add link-alt to fix card link accessibility (PR #89)

    • adds the link-alt option to card (and grid-item-card) directives, in order to assign a discernable name to the link (for screen readers).

  • 👌 IMPROVE: Make tab ids deterministic (PR #93)

    • Use increasing indices, rather than UUIDs

  • 🔧 MAINTAIN: Fix docutils PendingDeprecationWarning (PR #94)

  • 📚 DOCS: Update font awesome icons (PR #64)

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.2.0…v0.3.0

v0.2.0 - 2022-06-14

  • ⬆️ Support Sphinx v5, drop v3

  • ⬆️ Add Python 3.10 support

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.1.0…v0.2.0

v0.1.0 - 2022-04-21

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.0.13…v0.1.0

v0.0.13 - 2021-10-27

✨ NEW: add icon far role (PR #35), thanks to @OriolAbril

👌 IMPROVE: Styling for tabs (PR #21), thanks to @pradyunsg

👌 IMPROVE: Properly remove the border on dropdown card body (PR #23), thanks to @pradyunsg

🐛 FIX: sd-outline-* classes color (PR #25)

v0.0.11 - 2021-09-08

✨ NEW: Add ref-type option to button-ref directive

v0.0.10 - 2021-08-08

✨ NEW: Add grid-item directive child-direction and child-align options

✨ NEW: Add card directive img-background option

v0.0.9 - 2021-06-08

♻️ REFACTOR: test_sd_hide_root_title to sd_hide_title front-matter

👌 IMPROVE: dropdown chevrons

v0.0.8 - 2021-06-08

✨ NEW: Add test_sd_hide_root_title config option to hide the root title.

👌 IMPROVE: sd-card-hover:hover add scale 101%

📚 DOCS: Update landing page

v0.0.7 - 2021-05-08

✨ NEW: Add reverse option for grid directive

✨ NEW: Add animations

v0.0.6 - 2021-04-08

✨ NEW: Add card-carousel directive

v0.0.5 - 2021-28-07

👌 IMPROVE: Make octicon’s size variable

v0.0.4 - 2021-28-07

👌 IMPROVE: Allow auto for grid columns

v0.0.3 - 2021-26-07

👌 IMPROVE: Add more CSS classes and add documentation 📚

v0.0.2 - 2021-23-07

Improve documentation 📚

v0.0.1 - 2021-22-07

Initial release 🎉