{"id":10249,"library":"sphinx-panels","title":"Sphinx Panels","description":"sphinx-panels is a Sphinx extension that enables creating responsive panel layouts in reStructuredText or MyST Markdown. It allows arranging content into cards, grids, and more, leveraging Bootstrap-like CSS. The current version is 0.6.0, with releases occurring intermittently based on feature development and bug fixes.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-panels","tags":["Sphinx","documentation","UI","layout","reStructuredText","MyST"],"install":[{"cmd":"pip install sphinx-panels","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for Sphinx extensions.","package":"sphinx","optional":false}],"imports":[{"note":"Sphinx extensions are activated by adding their name to the `extensions` list in `conf.py`, not by importing Python modules directly into your project's code.","wrong":"from sphinx_panels import ...","symbol":"Extension activation","correct":"extensions = ['sphinx_panels']"}],"quickstart":{"code":"# conf.py\nproject = 'My Panel Project'\ncopyright = '2024, Your Name'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_panels' # Enable the extension\n]\n\nhtml_theme = 'alabaster'\n\n# example.rst (or .md if using MyST)\n# .. grid:: 1 2 2 3\n#    :gutter: 2\n#\n#    .. grid-item-card:: Card Title 1\n#       :shadow: sm\n#\n#       This is the content for the first card.\n#\n#    .. grid-item-card:: Card Title 2\n#       :shadow: sm\n#\n#       This is the content for the second card.\n#\n#    .. grid-item-card:: Card Title 3\n#       :shadow: sm\n#\n#       This is the content for the third card.","lang":"python","description":"To use sphinx-panels, first enable it in your Sphinx project's `conf.py` file by adding 'sphinx_panels' to the `extensions` list. Then, you can use directives like `.. grid::` or `.. panel::` in your reStructuredText or MyST Markdown files."},"warnings":[{"fix":"Consult the v0.2.0 changelog and updated documentation for the new class structure and directive options. Re-evaluate and update any custom CSS or directive usage.","message":"Prior to v0.2.0, sphinx-panels underwent a 'Major Revamp'. The CSS classes and internal structure for panels were significantly different. Existing `.. panel::` directives or custom CSS relying on pre-0.2.0 structure may break.","severity":"breaking","affected_versions":"<0.2.0 to 0.2.0+"},{"fix":"Update directive options to follow the new, more explicit syntax as shown in the latest documentation. For example, options might require a `key: value` format instead of just a bare `key`.","message":"In v0.3.0, the option syntax for directives like `.. panel::` or `.. grid::` was improved. Older, less explicit syntax might no longer be parsed correctly, leading to build failures or incorrect rendering.","severity":"breaking","affected_versions":"<0.3.0 to 0.3.0+"},{"fix":"If panels are not rendering as expected, use browser developer tools to inspect the generated HTML and CSS. Look for conflicting styles and consider adding custom CSS in your `_static/custom.css` to override them, or experiment with a different Sphinx theme.","message":"Some Sphinx themes may have CSS rules that conflict with `sphinx-panels`, especially regarding button styling or general layout, leading to unexpected rendering or overridden styles.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Add `'sphinx_panels'` to the `extensions` list in your Sphinx `conf.py` file.","cause":"The `sphinx_panels` extension has not been enabled in your Sphinx project's `conf.py` file.","error":"WARNING: Unknown directive type \"panel\"."},{"fix":"Check the official `sphinx-panels` documentation for the correct option syntax for your version. Ensure options are correctly indented and formatted (e.g., `key: value` for structured options).","cause":"Incorrect option syntax for a `grid`, `panel`, or other `sphinx-panels` directive, especially if migrating from older versions (pre-0.3.0).","error":"Invalid option block for 'grid' directive: not a block sequence. (or similar for syntax errors)"},{"fix":"Verify that `sphinx-panels` is correctly enabled in `conf.py`. Use your browser's developer tools to check if `sphinx-panels` CSS files are being loaded and if there are any console errors related to CSS. If theme conflicts are suspected, consider adding custom CSS overrides or testing with a default theme like `alabaster` or `furo`.","cause":"The CSS files for `sphinx-panels` might not be loading correctly, or there are significant CSS conflicts with your chosen Sphinx theme.","error":"Panels are not rendering correctly, appearing unstyled, or stacking vertically instead of in a grid."}]}