NewYour coding agent can read the release notes before it upgrades.Set up the MCP server β
PyPI
PyPI, #2356 most downloaded on PyPI
A sphinx extension for designing beautiful, view size responsive web components.
Latest stable
0.8.0
Last release 12 days ago
10 Nov 2026
Release timing varies
gaps range from 9 days to 1.5 years
Nearly every release is documented
notes for 22 of 23 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
23 releases Β· first in 2021
Drag across the ruler to compare, or tap a release to open it.
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 eβ¦
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.
Sphinx >=7.2 is 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 one
design.card_legacy warning, so a build run with -W fails until you do one of two things:
card-header and card-footer directives
(or the one-line :header: and :footer: options), which need sphinx-design 0.8.0 or later; or"design.card_legacy" to suppress_warnings in your conf.py.Once every card is migrated, set sd_card_legacy_separators = False to 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 localStorage instead of sessionStorage, so a chosen tab is remembered
across browsing sessions as well as across pages.
The storage key prefix is set by the new sd_tabs_storage_prefix option;
set it to an empty string to disable persistence ({pr}284, {issue}103).
Static assets are served through Sphinx's html_static_path, only for HTML-format builders.
A _sphinx_design_static directory 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-*-highlight hover and focus shades are now derived at runtime with color-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.findall helper is removed; call node.findall(...) directly ({pr}276).
The private CardDirective._create_component method is renamed _create_slot;
the old name stays as an alias for one release ({pr}294).
sd-card-text is 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).
accordion directive: groups dropdowns 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 {user}chrisjsewell in {pr}291aside directive: 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 {user}chrisjsewell in {pr}292 ({issue}97)steps and step directives for numbered procedures, with CSS-only number markers on an ordered list,
:start: and :color: options by {user}chrisjsewell in {pr}293card-header and card-footer directives, 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 {user}chrisjsewell in {pr}294tab-set and tab-set-code take :orientation: vertical, which stacks the labels
in a rail beside the selected panel from the md breakpoint up
by {user}kdeldycke in {pr}304 ({issue}219)link-new-tab flag on card and grid-item-card, and new-tab on
button-link and button-ref, for URLs and internal references alike
by {user}dipinknair in {pr}298 ({issue}170); tooltip suffix, rendered as a native HTML title;
for link and ref badges it applies after the explicit text <target> form, and \; escapes a literal semicolon
by {user}chrisjsewell in {pr}286 ({issue}81)tooltip role option,
so a reStructuredText custom role (.. role:: bdg-stable(bdg-success) with :tooltip:) or an extension
can preset a tooltip; a ; tooltip suffix still takes precedence
by {user}chrisjsewell in {pr}316button-link or button-ref text renders as separate lines
(<br /> in HTML, \newline{} in LaTeX), each line its own gettext message
by {user}Cherith1222 in {pr}308 and {user}chrisjsewell in {pr}315 ({issue}156)page.html#tab-name), or an element inside a tab panel,
opens that tab, on load and on hashchange by {user}chrisjsewell in {pr}284 ({issue}239)fa-solid, fa-brands, fa-regular), and CSS loading via the new
sd_fontawesome_source and sd_fontawesome_cdn_url options (the supported path for FontAwesome Pro kits)
by {user}chrisjsewell in {pr}285 ({issue}174)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 as before by {user}chrisjsewell in {pr}288 ({issue}174)sphinx_design.testing module with the normalize_doctree_xml helper, for downstream extensions'
doctree regression tests by {user}chrisjsewell in {pr}277 ({issue}260):focus-visible, so they do not show on mouse click) by {user}gabalafou in {pr}230, carried in {pr}283aria-controls attribute naming its panel
(this is not the full WAI-ARIA tabs pattern) by {user}chrisjsewell in {pr}283 ({issue}30)dchaudhari7177 in {pr}303 ({issue}301)sd_fontawesome_latex also accepts "fontawesome5" (loading fontawesome5.sty and emitting \faIcon{...}),
resolving package clashes with themes that load it; True and False work as before
by {user}chrisjsewell in {pr}285 ({issue}242)sd_* settings are declared in one typed configuration, and an invalid value warns
(design.config) and falls back to the default by {user}chrisjsewell in {pr}274chrisjsewell in {pr}290chrisjsewell in {pr}284 ({issue}46)tab-set with children other than tab-item warns for each one and renders the valid tabs,
instead of crashing with a ValueError by {user}chrisjsewell in {pr}258 ({issue}243)grid, card-carousel, tab-set and tab-set-code
no longer warn as invalid children, and targets are kept so references to them resolve,
including anchors to targets inside tabs by {user}chrisjsewell in {pr}271 and {pr}275 ({issue}86)button-link and button-ref keep their styling and links
by {user}sneakers-the-rat in {pr}264, carried in {pr}270 ({issue}96, {issue}44, {issue}263)button-ref keeps whitespace in reference targets (so multi-word labels, such as those from
autosectionlabel, resolve; ref targets are lowercased like the :ref: role), and renders nested inline content
like button-link by {user}chrisjsewell in {pr}281 ({issue}110, {issue}228):link: option keeps whitespace in reference targets,
and lowercases ref targets like the :ref: role by {user}chrisjsewell in {pr}282 ({issue}110)chrisjsewell in {pr}315article-info icons regain their sd-pr-2 spacing by {user}chrisjsewell in {pr}279 ({issue}99, {issue}117)sd-card-text
by {user}chrisjsewell in {pr}278 ({issue}40)_sphinx_design_static directory
by {user}chrisjsewell in {pr}276 ({issue}200, {issue}235)sd_fontawesome_latex row of the global options table no longer splits into an extra cell
by {user}yvonnefroehlich in {pr}297>=7.2,<10 by {user}chrisjsewell in {pr}276agent, library, release and sparkle),
12 redrawn icons and 37 extra sizes; no icon is removed (commit stays available)
by {user}kdeldycke in {pr}309chrisjsewell in {pr}267,
and the theme-pydata extra allows pydata-sphinx-theme<0.25 ({pr}313)flit_core>=3.4,<5 by {user}chrisjsewell in {pr}312gabalafou in {pr}158, carried in {pr}287chrisjsewell in {pr}273 ({issue}172, {issue}122, {issue}184, {issue}247)chrisjsewell in {pr}290stefmolin in {pr}229chrisjsewell in {pr}311chrisjsewell in {pr}289OCTICON_VERSION and OCTICON_CSS constants by {user}ftnext in {pr}205, carried in {pr}266Full changelog: https://github.com/executablebooks/sphinx-design/compare/v0.7.0...v0.8.0
Your coding agent can read these notes before it upgrades. Set up the MCP server β
π§ͺ add regression test for available material icons by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/224
muted, white, and black semantic colors by @user27182 in https://github.com/executablebooks/sphinx-design/pull/216AGENTS.md by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/251Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.6.1...v0.7.0
chrisjsewell in {pr}250chrisjsewell in {pr}250 and {pr}2552bndy5 in {pr}223muted, white, and black semantic colors by {user}agriyakhetarpal in {pr}216π Reduce right-padding of dropdown title by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/198
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.6.0...v0.6.1
chrisjsewell in {pr}212chrisjsewell in {pr}198β¬οΈ Python v3.9-3.12 by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/186
## What's Changed
### Dependencies
β¬οΈ Python v3.9-3.12 by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/186
β¬οΈ Octicon icons to v19.8.0 by @ffvpor in https://github.com/executablebooks/sphinx-design/pull/171
### 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:
```python 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 https://github.com/executablebooks/sphinx-design/pull/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
```restructuredtext .. tab-set-code:
.. literalinclude:: snippet.py
:language: python
.. literalinclude:: snippet.js
:language: javascript
```
The last selected tab key, per group, is also persisted SessionStorage
by @mikemckiernan and @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/196
### Improve
π Use reference name by default for internal link cards by @gabalafou in https://github.com/executablebooks/sphinx-design/pull/183
π Improve specificity of JS function name by @danirus in https://github.com/executablebooks/sphinx-design/pull/153
π Remove duplicate CSS hashing for sphinx >= 7.1 by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/193
#### π 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:
`css --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:
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 https://github.com/executablebooks/sphinx-design/pull/192
### Fix
π Fix tab-item label with nested syntax by @Praecordi in https://github.com/executablebooks/sphinx-design/pull/135
π Fix do not close input tag by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/195
### Internal
π Update theme versions by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/189
π Make octicon list a table by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/188
π Add sphinx-immaterial to doc theme builds by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/190
π Change syntax dropdown color by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/191
π§ Add FIPS compliant flag to md5 call by @gabor-varga in https://github.com/executablebooks/sphinx-design/pull/162
π§ define build.os for RTD to fix build by @sciencewhiz in https://github.com/executablebooks/sphinx-design/pull/176
π§ Move to ruff by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/185
## New Contributors
@danirus made their first contribution in https://github.com/executablebooks/sphinx-design/pull/153
@sciencewhiz made their first contribution in https://github.com/executablebooks/sphinx-design/pull/176
@ffvpor made their first contribution in https://github.com/executablebooks/sphinx-design/pull/171
@Praecordi made their first contribution in https://github.com/executablebooks/sphinx-design/pull/135
@gabor-varga made their first contribution in https://github.com/executablebooks/sphinx-design/pull/162
@gabalafou made their first contribution in https://github.com/executablebooks/sphinx-design/pull/183
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.5.0...v0.6.0
### Dependencies
β¬οΈ Python v3.9-3.12 by {user}`chrisjsewell` in {pr}`186`
β¬οΈ Octicon icons to v19.8.0 by {user}`ffvpor` in {pr}`171`
### 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:
```python 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 {user}`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
```restructuredtext .. 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 {user}`mikemckiernan` and {user}`chrisjsewell` in {pr}`196`
### Improve
π Use reference name by default for internal link cards by {user}`gabalafou` in {pr}`183`
π Improve specificity of JS function name by {user}`danirus` in {pr}`153`
π Remove duplicate CSS hashing for sphinx >= 7.1 by {user}`chrisjsewell` in {pr}`193`
#### π 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:
`css --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:
Also, the state chevron was previously two distinct SVGs (with one hidden), but now is one that get rotated on open/close.
by {user}`chrisjsewell` in {pr}`192`
### Fix
π Fix tab-item label with nested syntax by {user}`Praecordi` in {pr}`135`
π Fix do not close input tag by {user}`chrisjsewell` in {pr}`195`
### Internal
π Update theme versions by {user}`chrisjsewell` in {pr}`189`
π Make octicon list a table by {user}`chrisjsewell` in {pr}`188`
π Add sphinx-immaterial to doc theme builds by {user}`chrisjsewell` in {pr}`190`
π Change syntax dropdown color by {user}`chrisjsewell` in {pr}`191`
π§ Add FIPS compliant flag to md5 call by {user}`gabor-varga` in {pr}`162`
π§ define build.os for RTD to fix build by {user}`sciencewhiz` in {pr}`176`
π§ Move to ruff by {user}`chrisjsewell` in {pr}`185`
Full Changelog: <https://github.com/executablebooks/sphinx-design/compare/v0.5.0...v0.6.0>
β¬οΈ Drop Python 3.7 support, by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/146
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.4.1...v0.5.0
chrisjsewell in {pr}146chrisjsewell in {pr}148Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.4.1...v0.5.0
This is a minor release to bring in the following PR:
This is a minor release to bring in the following PR:
This release primarily brings in support for the latest versions of Sphinx and Python, and implements a few enhancements and bugfixes as well.
This release primarily brings in support for the latest versions of Sphinx and Python, and implements a few enhancements and bugfixes as well.
The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.
(GitHub contributors page for this release)
@akaszynski (activity) | @bastimeyer (activity) | @benjaoming (activity) | @choldgraf (activity) | @chrisjsewell (activity) | @codecov-commenter (activity) | @feanil (activity) | @jpmckinney (activity) | @LecrisUT (activity) | @marxin (activity) | @mikemckiernan (activity) | @nicoa (activity) | @pre-commit-ci (activity) | @spoorcc (activity) | @srideep3 (activity) | @tirthasheshpatel (activity) | @zerocewl (activity)
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.3.0...v0.4.0
124 ({user}feanil, {user}choldgraf)113 ({user}jpmckinney, {user}chrisjsewell)106105The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.
π§ MAINTAIN: Fix docutils PendingDeprecationWarning by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/94
link-alt to fix card link accessibility by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/89:name: options by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/91class-img-top/class-img-bottom by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/92PendingDeprecationWarning by @chrisjsewell in https://github.com/executablebooks/sphinx-design/pull/94Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.2.0...v0.3.0
2bndy5 ({pr}69):name: options ({pr}91)88)class-img-top/class-img-bottom ({pr}92)link-alt to fix card link accessibility ({pr}89)
link-alt option to card (and grid-item-card) directives, in order to assign a discernable name to the link (for screen readers).93)
PendingDeprecationWarning ({pr}94)64)Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.2.0...v0.3.0
[pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/executablebooks/sphinx-design/pull/63
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.1.0...v0.2.0
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.1.0...v0.2.0
β¬οΈ UPGRADE: octicons to v16.1.1 by @pocek in https://github.com/executablebooks/sphinx-design/pull/43
Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.0.13...v0.1.0
2bndy5 in {pr}41pocek in {pr}43chrisjsewell in {pr}59chrisjsewell in {pr}60chrisjsewell in {pr}58pradyunsg in {pr}22Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.0.13...v0.1.0
β¨ NEW: add icon far role ({pr}35), thanks to {user}OriolAbril
β¨ NEW: add icon far role ({pr}35), thanks to {user}OriolAbril
π IMPROVE: Styling for tabs ({pr}21), thanks to {user}pradyunsg
π IMPROVE: Properly remove the border on dropdown card body ({pr}23), thanks to {user}pradyunsg
π FIX: sd-outline-* classes color ({pr}25)
Nothing published for this version
β¨ NEW: Add ref-type option to button-ref directive
β¨ NEW: Add ref-type option to button-ref directive
β¨ NEW: Add grid-item directive child-direction and child-align options
β¨ NEW: Add grid-item directive child-direction and child-align options
β¨ NEW: Add card directive img-background option
β»οΈ REFACTOR: test_sd_hide_root_title to sd_hide_title front-matter
β»οΈ REFACTOR: test_sd_hide_root_title to sd_hide_title front-matter
π IMPROVE: dropdown chevrons
β¨ NEW: Add test_sd_hide_root_title config option to hide the root title.
β¨ 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
β¨ NEW: Add reverse option for grid directive
β¨ NEW: Add reverse option for grid directive
β¨ NEW: Add animations
β¨ NEW: Add card-carousel directive
β¨ NEW: Add card-carousel directive
π IMPROVE: Make octicon's size variable
π IMPROVE: Make octicon's size variable
π IMPROVE: Allow auto for grid columns
π IMPROVE: Allow auto for grid columns
π IMPROVE: Add more CSS classes and add documentation π
π IMPROVE: Add more CSS classes and add documentation π
Improve documentation π
Improve documentation π
Initial release π
Initial release π
One column per quarter.