快速上手

快速上手#

Chris Sewell

2025 年 09 月 18 日

1 min read

用法#

只需通过 pip 安装 sphinx-design 并将插件添加到您的 conf.py 文件中：

extensions = ["sphinx_design"]

为了与 MyST Parser 配合使用（用于 Markdown 文档），建议启用 colon_fence 语法扩展：

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

配置#

要隐藏页面的标题头，请在页面顶部添加：

---
sd_hide_title: true
---

:sd_hide_title:

创建自定义指令#

Added in version 0.6.0.

您可以在 conf.py 中使用 sd_custom_directives 配置选项来添加自定义指令，并设置默认选项值：

sd_custom_directives = {
    "dropdown-syntax": {
        "inherit": "dropdown",
        "argument": "Syntax",
        "options": {
            "color": "primary",
            "icon": "code",
        },
    }
}

键是要添加的新指令名称，值是包含以下键的字典：

  • inherit: 要继承的指令（例如 dropdown）

  • argument: 默认参数（可选，仅适用于接受单个参数的指令）

  • options: 指令的默认选项（可选）

支持的浏览器#

  • Chrome >= 60

  • Firefox >= 60

  • Firefox ESR

  • iOS >= 12

  • Safari >= 12

  • Explorer >= 12

(Mirrors: twbs/bootstrap)

从 sphinx-panels 迁移#

该包是作为 sphinx-panels 的迭代版本而诞生的，旨在使其更加灵活、更易于使用，并尽量减少与 Sphinx 主题的 CSS 冲突。

显著变化：

减少 CSS 类的直接使用#

这些被指令选项所取代，指令选项如下：

  • 更易于理解

  • 更易于验证

  • 更易于处理非 HTML 输出

  • 更易于改进/重构

panel 指令被取代#

panel 指令被顶层的 grid 指令取代，然后使用 grid-item-card 指令作为子元素，而不是通过 --- 分隔卡片。

如果不需要卡片，则可以使用 grid-item 指令，并且 card 也可以独立于网格使用。

大致上，.. panels:: 等同于 .. grid:: 1 2 2 2 并带有选项 :gutter: 2。

tabbed 指令被取代#

tabbed 指令被顶层的 tab-set 指令取代，然后使用 tab-item 指令作为子元素。

:sync: 选项允许跨集合同步选项卡选择。

tab-set-code 指令为同步代码示例提供了一种简写方式。

octicon 图标角色#

现在生成的默认 SVG 大小相对于周围文本（即使用 1em）。指定自定义大小和添加类的语法也发生了变化。

对于 favicon 图标也是如此，其中 , 分隔符也被替换为 ;，例如 :fa:`name,class` -> :fa:`name;class` 。

改善 CSS#

将 Bootstrap CSS 从 v4 更新到 v5，特别是允许顶层网格定义列数和间距大小。

所有 CSS 类都以 sd- 为前缀（不会与其他主题/扩展的 CSS 冲突）

所有颜色都使用 CSS 变量（可自定义）

目录