You need to enable JavaScript to run this app. 如何在Sphinx(reStructuredText)中实现自定义配色带编号的admonition
优惠活动
大模型
产品
解决方案
定价
更多

如何在Sphinx(reStructuredText)中实现自定义配色带编号的admonition

实现方案

第一步:修改conf.py注册自定义指令与编号逻辑

在你的项目conf.py末尾添加如下代码,这段代码会注册definition、theorem、example三类自定义admonition指令,同时实现按章节层级的连续编号逻辑:

from docutils import nodes
from docutils.parsers.rst import Directive, directives
from sphinx.util.docutils import SphinxDirective
from sphinx import addnodes

# 全局计数器,按章节存储当前编号
admonition_counter = {}

class CustomNumberedAdmonition(SphinxDirective):
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    has_content = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        # 获取当前章节的层级编号
        env = self.env
        docname = env.docname
        # 获取当前章节的编号字符串,如3.2.1
        section_num = env.toc_secnumbers.get(docname, {}).get(self.lineno, '')
        if not section_num:
            # 适配不同层级的章节编号获取
            for secinfo in env.toc_secnumbers.get(docname, {}).values():
                section_num = '.'.join(map(str, secinfo))
                break
        
        # 按章节维护连续计数器
        if section_num not in admonition_counter:
            admonition_counter[section_num] = 0
        admonition_counter[section_num] += 1
        current_num = f"{section_num}.{admonition_counter[section_num]}"

        # 生成admonition节点
        admonition_node = nodes.admonition()
        admonition_node['classes'].append(self.name)
        title_text = f"{current_num} {self.name.capitalize()}: {self.arguments[0]}"
        title_node = nodes.title(text=title_text)
        admonition_node += title_node

        # 解析内容
        self.state.nested_parse(self.content, self.content_offset, admonition_node)
        return [admonition_node]

def setup(app):
    # 注册三类自定义指令,可根据需要扩展更多类型
    app.add_directive('definition', CustomNumberedAdmonition)
    app.add_directive('theorem', CustomNumberedAdmonition)
    app.add_directive('example', CustomNumberedAdmonition)
    # 引入自定义样式,Sphinx 4.0+ 请替换为 add_css_file
    app.add_stylesheet('custom.css')

    # 每次构建前清空计数器
    def reset_counter(app, docname):
        admonition_counter.clear()
    app.connect('builder-inited', reset_counter)

第二步:编写custom.css配置配色样式

在你项目的_static目录下创建custom.css文件,添加如下样式,可根据需求调整配色值:

/* 公共自定义admonition样式 */
.admonition {
    border-radius: 4px;
    padding: 12px;
    margin: 16px 0;
}
.admonition .admonition-title {
    font-weight: bold;
    margin-top: 0;
    margin-bottom: 8px;
}

/* 定义类蓝色样式 */
.admonition.definition {
    border-left: 4px solid #2196F3;
    background-color: #E3F2FD;
}
.admonition.definition .admonition-title {
    color: #1976D2;
}

/* 定理类绿色样式 */
.admonition.theorem {
    border-left: 4px solid #4CAF50;
    background-color: #E8F5E9;
}
.admonition.theorem .admonition-title {
    color: #388E3C;
}

/* 示例类橙色样式 */
.admonition.example {
    border-left: 4px solid #FF9800;
    background-color: #FFF3E0;
}
.admonition.example .admonition-title {
    color: #F57C00;
}

第三步:使用测试

在你的rst文档中按你预期的语法编写即可:

Chapter
=======

.. definition:: My name of choice

   My definition here.

.. theorem:: my name of choice

   My theorem here.

在3.2.1小节下编写以上内容时,会自动渲染为编号3.2.1.1 Definition: My name of choice和3.2.1.2 Theorem: my name of choice的带配色admonition,和你预期的效果一致。


内容的提问来源于stack exchange,提问作者Hulda Hvönn

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.15 14:54:11