网络资产（CSS/JS/字体）#

此主题包含多个网络资产，以简化开发和设计。我们的资产编译配置在 webpack.config.js 中。

编译和捆绑资产#

当资产被编译时，静态版本将被放置在主题静态文件夹中的不同位置。

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static

对于许多资产，<hash> 被生成并附加到其在主题 HTML 模板中的引用末尾。这确保了当观众在升级主题后返回您的站点时，会提供正确的资产版本。

要编译资产并将它们与主题捆绑在一起，请运行以下命令。

$ tox -e run compile

样式（SCSS）和脚本（JS）#

CSS/JS 资产有两个相关的位置。

  • src/pydata_sphinx_theme/assets/styles 包含 SCSS 资产的源文件。这些文件将被编译成 CSS。

  • src/pydata_sphinx_theme/assets/scripts 包含 JS 资产的源文件。这些文件将被编译成 JS，并导入多个供应商库（如 Bootstrap）。

  • src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static 包含这些资产的编译版本（例如 CSS 文件）。此文件夹未在 .git 历史记录中跟踪，但它与主题的发布版捆绑在一起。

供应商脚本#

除了我们自己的 CSS 和 JS 之外，我们还提供了一些软件包。例如，Bootstrap、JQuery 和 Popper。这在 webpack.config.js 文件中配置，并在我们资产文件夹中的相应 SCSS 或 JS 文件中导入。

FontAwesome 图标#

三种“样式”的 FontAwesome 6 Free 图标字体被用于 图标链接 和警示，并且是唯一的 供应商 字体。

  • 它在 package.json 中作为依赖项进行管理。

  • 在编译时直接复制到网站静态文件中，包括许可证。

  • 部分预加载，以减少早期图标渲染的闪烁和伪影。

  • 在 webpack.config.js 中配置。

Jinja 宏#

我们的 Webpack 构建在 static/webpack-macros.html 文件中生成了一组 Jinja 宏。

这些宏在主 layout.html 文件中导入，然后插入页面上的不同位置以链接静态资产。

一些资产 “预加载”，这意味着浏览器在需要这些资源之前就开始请求它们。特别是，我们的 JavaScript 资产在 <head> 中预加载，并且脚本在 <body> 的末尾加载。