Getting Started

Chris Sewell

Jul 16, 2026

1 min read

Usage

Simply pip install sphinx-design and add the extension to your conf.py:

extensions = ["sphinx_design"]

For using with MyST Parser, for Markdown documentation, it is recommended to use the colon_fence syntax extension:

extensions = ["myst_parser", "sphinx_design"]
myst_enable_extensions = ["colon_fence"]

Note

The MyST Markdown examples in this documentation assume that certain optional MyST syntax extensions are enabled — extend the myst_enable_extensions list shown above with them as needed:

  • colon_fence: used by all examples, to write directives delimited by ::: fences

  • html_image: only for examples using raw HTML <img> tags, such as the avatar images in CSS Classes

  • attrs_inline: only for examples adding attributes to inline elements, such as the links to synchronised Tabs

Configuration

Global options

All global configuration options are prefixed with sd_, and can be set in your conf.py. Values are always simple, TOML-compatible, data types:

Name

Type

Default

Description

sd_custom_directives

dict[str, dict]

{}

Custom directives, inheriting from sphinx-design ones

sd_fontawesome_source

str

'none'

How sphinx-design loads the FontAwesome CSS: “none” (default, provided by you/your theme) or “cdn”

sd_fontawesome_cdn_url

str

'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css'

FontAwesome CSS URL to add when sd_fontawesome_source=”cdn”

sd_fontawesome_version

str

'as-named'

FontAwesome class scheme emitted by the icon roles: “as-named” (default, role name emitted verbatim), “4”, “5” or “6”

sd_fontawesome_latex

`bool

str`

False

sd_tabs_storage_prefix

str

'sphinx-design-tab-id-'

localStorage key prefix for persisting synced tab selections (an empty string disables persistence)

Hiding the page title

To hide the title header of a page, add to the top of the page:

---
sd_hide_title: true
---

:sd_hide_title:

Creating custom directives

Added in version 0.6.0.

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)

Supported browsers

sphinx-design targets Baseline Widely Available web features — those interoperable across Chrome, Edge, Firefox and Safari for at least 30 months (in practice, the evergreen browsers of roughly the last 2½ years). Internet Explorer is not supported.

Individual features may additionally use Baseline Newly Available CSS where it degrades gracefully; such exceptions are noted in the relevant feature’s documentation.

Migrating from sphinx-panels

This package arose as an iteration on sphinx-panels, with the intention to make it more flexible, easier to use, and minimise CSS clashes wth sphinx themes.

Notable changes:

Reduce direct use of CSS classes

These are replaced by the use of directive options, which are:

  • Easier to understand

  • Easier to validate

  • Easier to work with non-HTML outputs

  • Easier to improve/refactor

panel directive replaced

The panel directive is replaced by the use of the top-level grid directive, then using grid-item-card directive children, rather than delimiting cards by ---.

If no card is needed, then the grid-item directive can be used instead and card can be also used independently of grids.

Approximately, .. panels:: is equivalent to .. grid:: 1 2 2 2 with option :gutter: 2.

tabbed directive replaced

The tabbed directive is replaced by the use of the top-level tab-set directive, then using tab-item directive children.

The :sync: option allows to synchronize tab selection across sets.

The tab-set-code directive provides a shorthand for synced code examples.

octicon icon role

The default SVGs produced are now sized relative to the surrounding text (i.e. using 1em). The syntax for specifying a custom size and adding classes is also changed.

This is similar for favicon icons, where the , delimiter is also replaced by ;, e.g. :fa:`name,class` -> :fa:`name;class` .

Improved CSS

Updated Bootstrap CSS from v4 -> v5, which in particular allows top-level grid to define both column numbers and gutter sizes.

All CSS classes are prefixed with sd- (no clash with other theme/extension CSS)

All colors use CSS variables (customisable)