添加自定义 CSS 和 JS 资源#

如果您想修改此主题或页面上的部分内容，您需要向主题添加自定义 CSS 或 JavaScript。由于这是常见操作，在这里介绍几种方法。

示例站点结构

在以下所有示例中，假设有如下所示的站点结构：

mysphinxsite/
├── _static
│   ├── mycss.css
│   └── myjs.js
└── conf.py

首先：定义您的 html_static_path#

html_static_path 中列出的任何文件夹都将被视为包含构建的静态资源。这些文件夹中的所有文件都将在构建时复制到构建的 _static 文件夹中。例如，使用 HTML 构建器时，文件将复制到 _build/html/_static 中。

这些文件在复制时会被 扁平化，因此任何文件夹层次结构都会丢失。

列出包含静态资源的文件夹必须在以下任何方法之前完成。当您在以下方法中定义资源名称时，它们通常假定路径是 相对于此 _static 输出文件夹 的。

在 conf.py 中定义资源列表#

添加 JS 和 CSS 资源的最简单方法是在 conf.py 文件中使用 html_css_files 和 html_js_files。每个都可以是路径列表，相对于您的 html_static_path。它们将添加到站点 <head> 的末尾。

示例：

conf.py#
html_static_path = ["_static"]
html_css_files = ["mycss.css"]
html_js_files = ["myjs.js"]

这将导致每个文件在您的 <head> 中被链接。

将资源添加到您的 setup 函数中#

此外，您可以手动添加资源，为此，请使用 Sphinx setup() 函数 中的 app 对象。app 对象在这里有两个相关方法：

app.add_css_file 允许您直接添加 CSS 文件。

app.add_js_file 允许您直接添加 JS 文件。

Both of them expect you to add files relative to the html_static_path.

两者都希望您添加 相对于 html_static_path 的文件。

conf.py#
html_static_path = ["_static"]

def setup(app):
  app.add_css_file("mycss.css")
  app.add_js_file("myjs.js")

  # Add raw JavaScript
  rawjs = """
  let a = "foo";
  console.log(a + " bar")
  """
  app.add_js_file(None, body=rawjs)

使用事件将其添加到特定页面#

如果您想使用逻辑仅将脚本添加到某些页面或根据页面触发不同的行为，请使用 Sphinx 事件钩子。这涉及定义在 Sphinx 构建中发出特定事件时运行的函数，并使用 app.connect() 将其连接到您的构建。

您可能想要使用的事件是 html-page-context。这是在为 单个页面 创建 HTML 之前触发的。如果您运行 app.add_js_file 或 app.add_css_file，它将 仅添加到该页面。

示例：

conf.py#
html_static_path = ["_static"]

def add_my_files(app, pagename, templatename, context, doctree):
  if pagename == "dontaddonthispage":
    return

  app.add_css_file("mycss.css")

def setup(app):
  app.connect("html-page-context", add_my_files)

直接将其添加到页面内容中#

最后，您可以直接将 CSS 或 JS 添加到页面内容中。如果您使用 reStructuredText，可以使用 .. raw:: 指令；如果您使用 MyST Markdown，可以简单地将 HTML 内容内联到 Markdown 格式的内容中。

some_page_in_my_site.rst#
My title
========

Some text

.. raw:: html

    <style>
      /* Make h2 bigger */
      h2 {
        font-size: 3rem;
      }
    </style>

A bigger title
--------------

Some other text
some_page_in_my_site.md#
# My title

Some text

<style>
  /* Make h2 bigger */
  h2 {
    font-size: 3rem;
  }
</style>

## A bigger title

Some other text