{"id":1721,"library":"sphinx-design","title":"Sphinx Design","description":"Sphinx Design is a Sphinx extension that provides a rich set of directives and roles for creating modern, responsive, and visually appealing web components within your documentation. It offers features like cards, grids, dropdowns, tabs, and icon support. The library is actively maintained with frequent updates, often aligning with new Sphinx and Python releases, ensuring compatibility and introducing new design capabilities.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-design","tags":["Sphinx","documentation","UI","design","extension","responsive","cards","dropdowns"],"install":[{"cmd":"pip install sphinx-design","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for building documentation. Specific Sphinx versions are required for different sphinx-design versions.","package":"Sphinx","optional":false}],"imports":[{"note":"sphinx-design is enabled by adding its module name to the 'extensions' list in your Sphinx project's conf.py, not via a direct Python 'import' statement.","symbol":"sphinx_design","correct":"extensions = ['sphinx_design']"}],"quickstart":{"code":"import os\n\ndef create_minimal_conf_py():\n    conf_content = '''\nproject = 'My Design Docs'\ncopyright = '2023, Author'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx_design'\n]\nhtml_theme = 'furo'\n'''\n    with open('conf.py', 'w') as f:\n        f.write(conf_content)\n\n    # In a real scenario, you'd then create an index.rst or index.md like this:\n    # with open('index.rst', 'w') as f:\n    #     f.write('''\n    # My Design Docs\n    # ==============\n    #\n    # .. dropdown:: Click Me!\n    #    :color: primary\n    #\n    #    This is a dropdown content block.\n    #\n    # .. card:: Feature Card\n    #    :shadow: lg\n    #    :text-align: center\n    #\n    #    A simple card to highlight information.\n    #\n    #    :::{link-button} https://example.com\n    #    Visit Example\n    #    :::\n    # ''')\n\n    print(\"Generated conf.py with sphinx_design extension enabled.\")\n    print(\"To use directives, add them to your .rst or .md files (e.g., dropdown, card, grid).\")\n\nif __name__ == '__main__':\n    create_minimal_conf_py()\n","lang":"python","description":"To quickly enable `sphinx-design`, add `'sphinx_design'` to your `extensions` list in `conf.py`. After that, you can use its directives and roles (like `dropdown`, `card`, `grid`, `sd-icon`) directly in your reStructuredText or MyST Markdown files. The example demonstrates generating a `conf.py` and provides commented guidance for using directives in content files."},"warnings":[{"fix":"Always check the `sphinx-design` changelog before upgrading for the required Python version. For v0.7.0, Python >= 3.11 is required.","message":"Python version compatibility changes frequently with major `sphinx-design` releases. For example, v0.7.0 dropped support for Python 3.9 and 3.10.","severity":"breaking","affected_versions":"0.7.0, 0.5.0"},{"fix":"Consult the `sphinx-design` changelog or PyPI `Requires: Sphinx` metadata for the exact Sphinx version range. For v0.7.0, Sphinx v6 support was dropped, implying Sphinx v7+ is expected.","message":"Sphinx version compatibility is strictly managed. `sphinx-design` often drops support for older Sphinx versions while adding support for newer ones.","severity":"breaking","affected_versions":"0.7.0, 0.6.1, 0.5.0, 0.2.0"},{"fix":"Refer to the `sphinx-design` documentation for the latest supported icon names and categories if icons appear broken or are not found after an upgrade.","message":"Icon sets (Material Design Icons, Octicons) are periodically updated, which may change available icons or require updates to existing icon names.","severity":"gotcha","affected_versions":"All versions with icon updates (e.g., 0.7.0, 0.6.0, 0.3.0, 0.1.0)"},{"fix":"Upgrade to `sphinx-design` v0.6.0 or newer to utilize the `sd_custom_directives` feature for advanced customization of directives.","message":"The `sd_custom_directives` configuration option, allowing definition of custom directives with default options, was introduced in v0.6.0. Users on older versions cannot use this feature.","severity":"gotcha","affected_versions":"<0.6.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}