RestructuredText+sphinx-design：无标题图片自动编号方案咨询

核心思路 #

让Sphinx的编号系统识别图片元素，同时通过CSS隐藏默认标题，再调整网格卡片的间距消除冗余空白。

步骤1：添加自定义CSS规则 #

在项目的_static/custom.css文件中加入以下样式：

/* 隐藏figure的默认标题 */
.figure.hidden-caption .caption {
    display: none;
}

/* 消除grid-item-card底部多余间距 */
.sd-grid-item .sd-card {
    margin-bottom: 0;
    padding-bottom: 0;
}

确保conf.py中已配置加载自定义CSS：

html_static_path = ['_static']
html_css_files = ['custom.css']

步骤2：编写网格布局与图片指令 #

在RST文档中按以下结构编写，将图片和自定义标题分别放在独立网格项：

.. grid:: 1 2 2 3
    :gutter: 2

    .. grid-item-card::
        :class: sd-p-0  /* 去掉卡片内边距，避免多余空白 */

        .. figure:: path/to/your-image1.png
            :class: hidden-caption
            :name: fig:demo1
            :alt: 图片1的替代文本

            （此处留空或输入任意内容，都会被CSS隐藏）

    .. grid-item-card::
        :class: sd-text-center sd-p-2

        **自定义多行标题1**
        第二行标题内容
        第三行补充说明

    .. grid-item-card::
        :class: sd-p-0

        .. figure:: path/to/your-image2.png
            :class: hidden-caption
            :name: fig:demo2
            :alt: 图片2的替代文本

            （空内容）

    .. grid-item-card::
        :class: sd-text-center sd-p-2

        **自定义多行标题2**
        第二行标题内容

步骤3：验证:numref:引用 #

使用:numref:指令引用图片时，能正常生成带编号的链接：

如:numref:`fig:demo1`所示，这是第一张图片的引用效果。

备选方案：通过钩子自动添加隐藏类（进阶） #

如果不想手动给每个figure加hidden-caption类，可在conf.py中添加自定义指令钩子：

from sphinx.util.docutils import SphinxDirective
from docutils.parsers.rst.directives.images import Figure

class HiddenCaptionFigure(Figure):
    def run(self):
        result = super().run()
        if result and hasattr(result[0], 'set_class'):
            result[0].set_class('hidden-caption')
        return result

def setup(app):
    app.add_directive('hidden-figure', HiddenCaptionFigure)

之后在RST中用.. hidden-figure::代替.. figure::即可，无需手动添加类。

关键注意事项 #

1. 确保conf.py中开启自动编号：numfig = True
2. 用浏览器开发者工具检查网格卡片的margin/padding，可根据实际视觉效果微调CSS参数
3. 图片的:name:属性必须唯一，否则:numref:无法正确匹配

内容的提问来源于stack exchange，提问作者Manuel Yguel