Change Log#
0.8.0 - 2026-11-10#
New components (accordion, aside, steps, vertical tab sets, and explicit card header and footer directives), links that open in a new tab, badge tooltips, a plain-CSS build with no Sass, tab selections that persist across pages and visits, accessibility fixes, FontAwesome v6 support, and Octicons v19.42.0. Sphinx 7.2 or later is now required.
Upgrade notes#
Sphinx
>=7.2is required (Sphinx 7.0 and 7.1 are no longer supported); Python stays at>=3.11(PR #276).The
^^^and+++card separators are deprecated and warn by default. They still render as before, but the first card in a document that uses them emits onedesign.card_legacywarning, so a build run with-Wfails until you do one of two things:move the header and footer into the new
card-headerandcard-footerdirectives (or the one-line:header:and:footer:options), which need sphinx-design 0.8.0 or later; oradd
"design.card_legacy"tosuppress_warningsin yourconf.py.
Once every card is migrated, set
sd_card_legacy_separators = Falseto stop scanning for the separators. The plan is to turn the separators off by default in 1.0 and remove them in 2.0; the cards page has a migration table (PR #294).Tab selections persist in
localStorageinstead ofsessionStorage, so a chosen tab is remembered across browsing sessions as well as across pages. The storage key prefix is set by the newsd_tabs_storage_prefixoption; set it to an empty string to disable persistence (PR #284, #103).Static assets are served through Sphinx’s
html_static_path, only for HTML-format builders. A_sphinx_design_staticdirectory left in an existing build directory by an earlier version is unused and can be deleted (PR #276).The stylesheet is plain CSS, generated without Sass. The
--sd-color-*-highlighthover and focus shades are now derived at runtime withcolor-mix()(behind the old value as a static fallback), so overriding a--sd-color-*variable now also changes its hover shade (PR #290).The private
sphinx_design._compat.findallhelper is removed; callnode.findall(...)directly (PR #276). The privateCardDirective._create_componentmethod is renamed_create_slot; the old name stays as an alias for one release (PR #294).sd-card-textis added only to the direct child paragraphs of a card or dropdown body, and is added to a paragraph’s classes instead of replacing them; paragraphs nested deeper (in admonitions, lists, nested tab sets) no longer get it (PR #278).
New#
✨
accordiondirective: groupsdropdowns so that opening one closes the others, using the browser’s native<details name>behaviour with no JavaScript;:flush:renders it edge to edge by @chrisjsewell in PR #291✨
asidedirective: a call-out box floated beside the body text (:align:,:width:), rendered as a semantic<aside>in HTML and a plain titled container elsewhere by @chrisjsewell in PR #292 (#97)✨
stepsandstepdirectives for numbered procedures, with CSS-only number markers on an ordered list,:start:and:color:options by @chrisjsewell in PR #293✨
card-headerandcard-footerdirectives, and:header:and:footer:options, for card and grid-item-card headers and footers: the card body is parsed once as ordinary content, and errors in a header or footer report their own line (see the upgrade notes for the legacy separators) by @chrisjsewell in PR #294✨ Vertical tab sets:
tab-setandtab-set-codetake:orientation: vertical, which stacks the labels in a rail beside the selected panel from themdbreakpoint up by @kdeldycke in PR #304 (#219)✨ Open links in a new tab: the
link-new-tabflag oncardandgrid-item-card, andnew-tabonbutton-linkandbutton-ref, for URLs and internal references alike by @dipinknair in PR #298 (#170)✨ Badge tooltips: badge roles accept a trailing
; tooltipsuffix, rendered as a native HTMLtitle; for link and ref badges it applies after the explicittext <target>form, and\;escapes a literal semicolon by @chrisjsewell in PR #286 (#81)✨ Every badge role (plain, line, link and ref, in every colour) accepts a
tooltiprole option, so a reStructuredText custom role (.. role:: bdg-stable(bdg-success)with:tooltip:) or an extension can preset a tooltip; a; tooltipsuffix still takes precedence by @chrisjsewell in PR #316✨ A line block in
button-linkorbutton-reftext renders as separate lines (<br />in HTML,\newline{}in LaTeX), each line its own gettext message by @Cherith1222 in PR #308 and @chrisjsewell in PR #315 (#156)✨ A URL fragment that targets a tab (e.g.
page.html#tab-name), or an element inside a tab panel, opens that tab, on load and onhashchangeby @chrisjsewell in PR #284 (#239)✨ FontAwesome v6 roles (
fa-solid,fa-brands,fa-regular), and CSS loading via the newsd_fontawesome_sourceandsd_fontawesome_cdn_urloptions (the supported path for FontAwesome Pro kits) by @chrisjsewell in PR #285 (#174)✨
sd_fontawesome_versionmakes 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-lineconf.pychange; the default"as-named"keeps emitting the role name as before by @chrisjsewell in PR #288 (#174)✨
sphinx_design.testingmodule with thenormalize_doctree_xmlhelper, for downstream extensions’ doctree regression tests by @chrisjsewell in PR #277 (#260)
Improve#
👌 Keyboard focus rings restored on tab labels, dropdown summaries, buttons and stretched-link cards (with
:focus-visible, so they do not show on mouse click) by @gabalafou in PR #230, carried in PR #283👌 Each tab label carries an
aria-controlsattribute naming its panel (this is not the full WAI-ARIA tabs pattern) by @chrisjsewell in PR #283 (#30)👌 The tab hover colour is the active colour at 80% opacity, so a hovered tab no longer looks selected by @dchaudhari7177 in PR #303 (#301)
👌
sd_fontawesome_latexalso accepts"fontawesome5"(loadingfontawesome5.styand emitting\faIcon{...}), resolving package clashes with themes that load it;TrueandFalsework as before by @chrisjsewell in PR #285 (#242)👌 All
sd_*settings are declared in one typed configuration, and an invalid value warns (design.config) and falls back to the default by @chrisjsewell in PR #274👌 Plain-CSS stylesheet generated by a dependency-free Python tool (no Sass or Node), with the dead vendor-prefixed declarations removed by @chrisjsewell in PR #290
Fix#
🐛 Synced tabs stay in sync when activated by keyboard or click-and-drag by @chrisjsewell in PR #284 (#46)
🐛 A
tab-setwith children other thantab-itemwarns for each one and renders the valid tabs, instead of crashing with aValueErrorby @chrisjsewell in PR #258 (#243)🐛 Comments, hyperlink targets and system messages inside
grid,card-carousel,tab-setandtab-set-codeno longer warn as invalid children, and targets are kept so references to them resolve, including anchors to targets inside tabs by @chrisjsewell in PR #271 and PR #275 (#86)🐛 Buttons survive gettext translation: translated
button-linkandbutton-refkeep their styling and links by @sneakers-the-rat in PR #264, carried in PR #270 (#96, #44, #263)🐛
button-refkeeps whitespace in reference targets (so multi-word labels, such as those fromautosectionlabel, resolve;reftargets are lowercased like the:ref:role), and renders nested inline content likebutton-linkby @chrisjsewell in PR #281 (#110, #228)🐛 The card and grid-item-card
:link:option keeps whitespace in reference targets, and lowercasesreftargets like the:ref:role by @chrisjsewell in PR #282 (#110)🐛 Messages and gettext locations for button text name its first content line in reStructuredText (they named a later line, or the including page for a button in an included file) by @chrisjsewell in PR #315
🐛 Icon roles no longer leak SVG markup into toctree labels and the search index, and
article-infoicons regain theirsd-pr-2spacing by @chrisjsewell in PR #279 (#99, #117)🐛 Dropdowns no longer overwrite user classes on their paragraphs with
sd-card-textby @chrisjsewell in PR #278 (#40)🐛 Non-HTML builds no longer gain a spurious
_sphinx_design_staticdirectory by @chrisjsewell in PR #276 (#200, #235)🐛 The
sd_fontawesome_latexrow of the global options table no longer splits into an extra cell by @yvonnefroehlich in PR #297
Dependencies#
⬆️ Sphinx
>=7.2,<10by @chrisjsewell in PR #276⬆️ Octicons v19.8.0 to v19.42.0: 81 new icons (such as
agent,library,releaseandsparkle), 12 redrawn icons and 37 extra sizes; no icon is removed (commitstays available) by @kdeldycke in PR #309⬆️ Theme extras refreshed to current releases by @chrisjsewell in PR #267, and the
theme-pydataextra allowspydata-sphinx-theme<0.25(PR #313)⬆️ The build backend allows
flit_core>=3.4,<5by @chrisjsewell in PR #312
Docs#
📚 Buttons are documented as links styled as buttons, with an accessibility note by @gabalafou in PR #158, carried in PR #287
📚 Sizing classes, multiple grid rows, links to synchronised tabs, and the MyST extensions the examples need by @chrisjsewell in PR #273 (#172, #122, #184, #247)
📚 A browser support policy (Baseline Widely Available) and a “Design: the CSS pipeline” page by @chrisjsewell in PR #290
📚 Fix a typo in the get started page by @stefmolin in PR #229
Internal#
🔧 Releases are published to PyPI with trusted publishing, and every pull request builds and checks the distributions by @chrisjsewell in PR #311
🔧 CI compiles the documentation PDF by @chrisjsewell in PR #289
♻️ Remove the unused
OCTICON_VERSIONandOCTICON_CSSconstants by @ftnext in PR #205, carried in PR #266
0.7.0 - 2026-01-19#
Dependencies#
⬆️ Drop Python 3.9 & 3.10, support Python 3.14 by @chrisjsewell in PR #250
⬆️ Drop Sphinx v6, add Sphinx v9 support by @chrisjsewell in PR #250 and PR #255
⬆️ Update Material Design Icons to v4.0.0-116-ge9da21 by @2bndy5 in PR #223
Docs#
📚 Document
muted,white, andblacksemantic colors by @agriyakhetarpal in PR #216
0.6.1 - 2024-08-02#
⬆️ Update sphinx to >=6,<9 by @chrisjsewell in PR #212
👌 Reduce right-padding of dropdown title by @chrisjsewell in PR #198
0.6.0 - 2024-05-23#
Dependencies#
⬆️ Python v3.9-3.12 by @chrisjsewell in PR #186
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#
👌 Use reference name by default for internal link cards by @gabalafou in PR #183
👌 Improve specificity of JS function name by @danirus in PR #153
👌 Remove duplicate CSS hashing for sphinx >= 7.1 by @chrisjsewell in PR #193
👌 Improve dropdown title bar#
There are three visible changes:
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-updirective option.The prefix icon (optional), title text, and chevron state icon are now all better aligned
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 ( |
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#
🐛 Fix tab-item label with nested syntax by @Praecordi in PR #135
🐛 Fix do not close
inputtag by @chrisjsewell in PR #195
Internal#
📚 Update theme versions by @chrisjsewell in PR #189
📚 Make octicon list a table by @chrisjsewell in PR #188
📚 Add sphinx-immaterial to doc theme builds by @chrisjsewell in PR #190
📚 Change syntax dropdown color by @chrisjsewell in PR #191
🔧 Add FIPS compliant flag to md5 call by @gabor-varga in PR #162
🔧 define
build.osfor RTD to fix build by @sciencewhiz in PR #176🔧 Move to ruff by @chrisjsewell in PR #185
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.5.0…v0.6.0
0.5.0 - 2023-07-27#
⬆️ Drop Python 3.7 support, by @chrisjsewell in PR #146
⬆️ UPGRADE: sphinx>=5,<8, by @chrisjsewell in PR #148
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#
Make default blue color a11y friendly. PR #124 (@feanil, @choldgraf)
Make card titles translatable PR #113 (@jpmckinney, @chrisjsewell)
Version upgrades#
Contributors to this release#
The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.
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-altto fix card link accessibility (PR #89)adds the
link-altoption tocard(andgrid-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#
✨ NEW: Add material design icons roles, thanks to @2bndy5 in PR #41
🐛 FIX: Links in card titles by @chrisjsewell in PR #59
🐛 FIX: Exception on missing card link by @chrisjsewell in PR #60
🔧 MAINTAIN: Move from setuptools to flit for package build by @chrisjsewell in PR #58
🔧 MAINTAIN: Drop furo-specific stylesheet, thanks to @pradyunsg in PR #22
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 🎉