高级HTML输出

高级HTML输出#

自定义CSS或JavaScript#

如果你希望在你的书中包含自定义的CSS规则或JavaScript脚本，可以将它们添加到你的书文件夹中的名为_static的文件夹中。此文件夹中以.css或.js结尾的任何文件都将自动复制到你构建的书的HTML中，并链接到每页的头部。

例如，要在具有以下结构的Jupyter Book文件夹中包含一个自定义的CSS文件myfile.css：

mybook/
├── _config.yml
├── _toc.yml
└── page1.md

将静态文件添加到这里：

├── _config.yml
├── _toc.yml
├── page1.md
└── _static
    └── myfile.css

然后，规则应自动应用于你的站点。通常，这些CSS和JS文件将在页面上的其他文件加载后加载，因此它们应该会覆盖预先存在的规则和行为。

示例：两端对齐文本#

如果你希望你的书的文本是两端对齐而不是左对齐，则在mybook/_static下创建myfile.css，并添加以下CSS：

p {
    text-align: justify;
}

示例：自定义提醒框#

Warning

以这种方式设置自定义提醒框的样式不受Jupyter Book或Sphinx的官方支持，因此其行为可能会意外变化。一种更详细但“稳定”的方法是使用创建提醒框时的:class:关键字参数，并为该类定义CSS规则。

目前，使用带有标题的{admonition}指令会根据提醒框的标题创建一个CSS类。例如，标题为Here's my title的提醒框将生成一个名为admonition-here-s-my-title的类名。

另一方面，通过使用:class:关键字参数，它将创建一个以前选择的类的类名。例如，定义为my-custom-class的自定义类将生成一个名为my-custom-class的类。

你可以利用这些模式中的任何一个来快速创建自定义提醒框。下面是每种情况的示例。在每种情况下，首先在mybook/_static下创建一个myadmonitions.css文件，并添加CSS规则到其中。

使用带有标题的{admonition}指令

div.admonition-extra-credit {
    border-left-color: rgba(0, 246, 16, 1);
}
div.admonition-extra-credit .admonition-title {
    background-color: rgba(0, 246, 16, .1);
}
div.admonition-extra-credit .admonition-title:before {
    color: rgba(0, 246, 16, 1);
    content: '\f19d';
}

然后，在你的书中，定义一个提醒框如下：

```{admonition} Extra credit
这里提供了一个“额外学分”的练习。
```

使用:class:关键字参数

div.extra-credit {
    border-left-color: rgba(var(--pst-color-success), 1);
}
div.extra-credit .admonition-title {
    background-color: rgba(var(--pst-color-success), .1)
}
div.extra-credit .admonition-title:before {
    color: rgba(var(--pst-color-success), 1);
    content: '\f19d';
}

然后，在你的书中，定义一个提醒框如下：

```{admonition} An extra exercise
:class: extra-credit
这里提供了一个“额外学分”的练习。
```

在这两种情况下，当你构建你的书时，提醒框应根据你的CSS规则进行样式化。

示例：为站点名称和搜索路径添加结构化数据#

对于HTML构建，结构化数据使机器能更好地理解你的页面内容。例如，Google搜索可以使用结构化数据来理解你的站点名称，提供直接在你的站点内搜索的搜索框，为抽认卡或测验提供互动体验等：参见Google搜索支持的结构化数据标记。

你可以使用JSON for Linking Data (JSON-LD)格式和几行JavaScript轻松为你的站点名称提供结构化数据，将JSON-LD数据注入到你的页面中。这些可以直接添加为_static目录中的单个文件，如自定义资产中所述。例如，你可以将文件命名为structured_data.js。以下是一个示例，显示了jupyterbook.org的站点名称和搜索路径信息：

var structuredData = {
"@context" : "https://schema.org",
"@type" : "WebSite",
"name" : "jupyter{book}",
"alternateName" : "JB",
"url" : "https://jupyterbook.org/",
"potentialAction": {
"@type": "SearchAction",
"target": {
  "@type": "EntryPoint",
  "urlTemplate": "https://jupyterbook.org/en/stable/search.html?q={search_term_string}"
},
"query-input": "required name=search_term_string"
}
};

const SDscript = document.createElement('script');
SDscript.setAttribute('type', 'application/ld+json');
SDscript.textContent = JSON.stringify(structuredData);
document.head.appendChild(SDscript);

要为您的站点使用此脚本，请根据您的 JupyterBook 配置修改 name、alternateName、url 和 urlTemplate。对于 urlTemplate，最简单的方法是在您的站点上进行搜索，然后从返回结果的 URL 中提取搜索路径。

启用 Google Analytics#

如果您有 Google 账户，您可以使用 Google Analytics 来收集一些关于访问您 Jupyter Book 流量的信息。通过此工具，您可以了解有多少人在使用您的书籍、他们的来源以及访问方式（无论是通过桌面版还是移动版等）。

要为您的 Jupyter Book 添加 Google Analytics，请访问 Google Analytics，创建一个新的 Google Analytics 账户，并为您的 Jupyter Book 创建一个新的 property。接下来的步骤取决于您使用的 Google Analytics 版本：

如果使用 Google Analytics 4（GA4）：
- 您还需要为您的 property 创建一个 stream。
- 选择创建一个 web stream 并提供您的 Jupyter book 的 URL。
- 复制与该 stream 关联的 Measurement ID。这是一个类似于 G-XXXXXXX 的字母数字代码。
如果使用 Google Analytics 的旧版本，如 Google Analytics 3：
- 在创建 property 时提供您的 Jupyter Book 的 URL。
- 复制该 property 的 analytics “tracking ID”。这是一个类似于 UA-XXXXXX-X 的数字代码。

将 Measurement ID（GA4）或 tracking ID（Google Analytics 的旧版本）粘贴到配置文件中的以下指令中：

html:
  analytics:
    google_analytics_id: G-XXXXXXX

使用 Plausible Analytics#

Plausible Analytics 是一种轻量级、开源的、隐私优先的分析服务，可以用作更合乎道德的 Google Analytics 替代方案（或与之并存）。

Plausible Analytics 需要一个域名，该域名由 plausible_analytics_domain 属性提供：

html:
  analytics:
    plausible_analytics_domain: my-domain

您可以指定加载的分析脚本；默认情况下，使用来自 https://plausible.io 的 bundle：

html:
  analytics:
    plausible_analytics_domain: my-domain
    plausible_analytics_url: https://plausible.io/js/script.js

这应该会将适当的代码注入到构建的站点中，您将能够通过商业公司托管的仪表板或自托管实例获取网站的分析数据。

检查书籍中的外部链接#

如果您想确保书籍中的外部链接是有效的，可以使用 Jupyter Book 运行 Sphinx 链接检查器。这将检查您的外部链接并确保它们能解析。

要运行链接检查器，请使用以下命令：

jupyter-book build mybookname/ --builder linkcheck

它将打印您书籍中每个链接的状态，以便您稍后解决任何不正确的链接。

在 Markdown 中使用原始 HTML#

Jupyter Notebook Markdown 允许您在 Markdown 单元格中使用原始 HTML。在大多数情况下，这并不推荐，因为它通常会作为原始文本传递到构建过程中，因此不会经过诸如：

相对路径修正
将资产复制到构建文件夹
多种输出类型格式化（例如，它不会显示在 PDFs 中！）等处理。

因此，例如，我们在下面添加：

<a href="../intro.md">Go Home HTML!</a>

[Go Home Markdown!](../intro.md)

您会发现 HTML 链接是断开的：

Go Home HTML!

Go Home Markdown!

Tip

请注意，MyST Markdown 现在有一些扩展语法特性，可以让您以正确的方式使用某些 HTML 元素。

例如，原始 HTML 图像标签

<img src="../images/fun-fish.png" alt="the fun fish!" width="200px"/>

变为

详情请参见图像部分。

为您的书籍添加额外 HTML#

在 Jupyter Book 中有几个地方可以添加额外的任意 HTML。在所有情况下，这都是通过 _config.yml 文件中的配置值完成的。

在页脚中添加额外 HTML#

要在书籍的页脚中添加额外 HTML，请使用以下配置：

html:
    extra_footer: |
        <div>
            your html
        </div>

extra_footer的内容将会在页面的所有其他页脚内容之后插入到HTML中。

向左侧导航栏添加额外的HTML#

要在你的书籍左侧导航栏中添加额外的HTML，请使用以下配置：

html:
    extra_navbar: |
        <div>
            your html
        </div>

extra_navbar的内容将会在页面的所有其他HTML内容之后插入到HTML中。

向HTML页脚添加许可证#

如果你想为你的书籍添加更详细的许可证，或者想为许可证添加一个指向外部页面的链接，最简单的方法是为此使用自定义页脚。你可以禁用自动添加到每个页脚的“版权”文本，并添加你喜欢的任何页脚HTML。

例如，请参见以下配置：

html:
  extra_footer: |
    <p>
    ... 在此处添加许可证信息...
    </p>
sphinx:
  config:
    html_show_copyright: false

请注意，这可能不适用于由LaTeX生成的PDF页面构建。

手动指定要包含在网站中的额外文件/文件夹#

Jupyter Book会复制其页面中链接的所有文件，以使链接在生成的网站中正常工作。然而，有时你可能希望手动确保文件和文件夹包含在你的生成网站中。例如，如果你希望从生成的文档外部链接到它们，而不是从生成的文档内部链接到它们。

要手动指定要复制的项目，请使用html_extra_path Sphinx配置。你可以像这样使用Jupyter Book进行配置：

sphinx:
  config:
    html_extra_path: ['folder1', 'folder2']

当你构建书籍的HTML时，Jupyter Book将确保html_extra_path中指定的文件夹内的所有文件和文件夹都会被复制到你的生成网站中。

例如，如果你的书籍中有如下文件夹结构：

assets
└── data
    └── mydataset.csv

以及以下Jupyter Book配置：

sphinx:
  config:
    html_extra_path: ['assets']

那么数据集将可以通过yourwebsite.com/data/mydataset.csv访问。

配置以提高可访问性#

声明你的书籍中使用的主要语言有助于屏幕阅读器和浏览器翻译工具。

可以通过在_config.yml文件中的sphinx配置下，向language选项提供适当的语言代码来配置语言：

sphinx:
  config:
    language: en

此示例将书籍语言设置为英语，这将在你的书籍HTML中表示为<html lang="en">...</html>。