快速上手

快速上手#

简短的逐步教程，帮助您开始使用 Sphinx Book 主题。

备注

本文档和下面的示例使用 MyST Markdown 编写，这是一种与 Sphinx 一起使用的标记语言。有关 MyST markdown 的更多信息，以及如何将其与您的 Sphinx 网站一起使用，请参阅 MyST-parser 文档。

您应该对 Sphinx 生态系统有所了解，并且已经在本地计算机上安装了它。

备注

如果您还没有准备好进行自定义的 Sphinx 站点，可以使用以下命令创建：

sphinx-quickstart

首先使用 pip 安装 sphinx-book-theme：

pip install sphinx-book-theme

然后，在您的 Sphinx 配置文件（ conf.py ）中激活主题：

...
html_theme = "sphinx_book_theme"
...

这将为您的文档激活 Sphinx Book 主题。

备注

您可能需要根据您的先前的主题注释掉您的 html_theme_options 配置。

有几种方法可以自定义 Sphinx Book Theme。对于本教程将添加指向主题的 GitHub 存储库的指针。

要向您的主题添加指向存储库的按钮，请在 conf.py 中添加以下配置。

html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    "use_repository_button": True,
    ...
}

当您构建文档时，您的页眉现在应该包含指向存储库的小 GitHub 徽标。

参见

您可以通过 Book 主题自定义页面的几个主要区域。最常见的是 主侧边栏 （默认情况下，位于页面左侧）。

侧边栏元素由 Sphinx、Sphinx 插件和当前主题定义为 HTML 模板。您可以使用 html_sidebars 配置指定哪些页面应包含哪些侧边栏元素。在本教程中，将跳过此步骤，但如果您想了解更多信息，请参阅控制左侧边栏项目。

自定义站点的徽标。为此，将编辑 html_logo 和 html_title 配置选项。

为了添加站点徽标，请按照以下步骤操作：

放置图像在您的文档根目录（例如，myimage.png）。
添加一行到您的 conf.py 文件，如下所示：
```
html_logo = "path/to/myimage.png"
```
路径相对于 conf.py 文件。

接下来，将 自定义站点标题。为此，请在您的 conf.py 文件中添加一行，如下所示：

html_title = "My site title"

此标题现在将放置在 logo 下方。

本主题支持几种特殊类型的内容，主要受到 Tufte CSS 主题样式的启发。其中一种内容是 边距内容。这允许您将内容“弹出”到页面侧边，即边距中。通过添加以下指令（使用 MyST Markdown 编写），为页面添加一些边距内容。

```{margin} Look, some margin content!
On wider screens, this content will pop out to the side!
```

在宽屏幕上，边距内容将弹出到页面的侧边，并允许其下方的内容向上移动。这使您可以提供额外的信息，而不会中断信息的流动。

使用 Sphinx Book 主题还有许多其他事情可以做。现在您已经开始了，查看左侧的其他部分，了解如何使用它的更多信息。