添加自定义 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 资产的最简单方法是使用 html_css_files 和 html_js_files 在你的 conf.py 文件中。每个都可以是一个路径列表，相对于你的 html_static_path。它们将被添加到站点 <head> 的末尾。

例如

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

这将导致每个在你的 <head> 中链接。

将资产添加到你的设置函数#

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

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

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

两者都期望你添加相对于 html_static_path 的文件。

此外，app.add_js_file 允许你除了链接文件之外还添加原始 JavaScript（见下面的示例）。例如

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