特殊内容块

这个主题有一些独特的内容区块

引言和题词

以下是引言和题词在 sphinx-book-theme 中的样式：

默认 markdown 引言

> Here's my quote, it's pretty neat.
> I wonder how many lines I can create with
> a single stream-of-consciousness quote.
> I could try to add a list of ideas to talk about.
> I suppose I could just keep going on forever,
> but I'll stop here.

Here's my quote, it's pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I'll stop here.

有时你想要对一段引言给予更多关注。为此，请使用 {epigraph} 指令。下面的题词，点击它右侧的按钮以显示用于生成它的代码：

基础引言

```{epigraph}
Here's my quote, it's pretty neat.
I wonder how many lines I can create with
a single stream-of-consciousness quote.
I could try to add a list of ideas to talk about.
I suppose I could just keep going on forever,
but I'll stop here.
```

Here's my quote, it's pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I'll stop here.

你还可以通过添加空行，然后添加以 -- 开头的行来为题词添加出处。这将呈现如下：

带有出处的题词

```{epigraph}
Here's my quote, it's pretty neat.
I wonder how many lines I can create with
a single stream-of-consciousness quote.
I could try to add a list of ideas to talk about.
I suppose I could just keep going on forever,
but I'll stop here.

-- Jo the Jovyan, *[the jupyter book docs](https://jupyterbook.org)*
```

Here's my quote, it's pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I'll stop here.

—Jo the Jovyan, the jupyter book docs

旁注和边注

这个主题支持 Tufte 风格的页边/侧边注释，其用户体验类似于 pandoc-sidenote。

侧边注释是编号的，其行为类似于脚注，但它们位于页边，不会迫使读者将视线跳到页面底部。例如，这里有侧边注释 ^{1 1}Here's my sidenote text!。在窄屏幕上，侧边注释默认是隐藏的，直到用户点击编号才会显示。如果你正在使用移动设备，可以尝试点击上面的侧边注释编号。

页边注释没有编号，但行为与侧边注释相同。在移动设备上，你会看到一个符号，点击该符号即可显示页边注释 This is a margin note. Notice there isn’t a number preceding the note.。例如，在前面的句子中有一个页边注释，在移动屏幕上你应该会看到一个符号来显示它。

参见

侧边注释和页边注释是内联内容——你不能在这些注释中使用块级内容。如果你想在页边使用块级内容，请参阅 使用 {margin} 指令的块级页边内容。

启用侧边注释和页边注释

该主题通过覆盖脚注语法，使侧边注释和页边注释在页边显示，从而激活它们。

要将你的脚注转换为侧边注释/页边注释，请使用以下配置：

html_theme_options = {
  ...
  "use_sidenotes": True,
  ...
}

这将把你的 脚注 转换为 侧边注释 或 页边注释。

创建侧边注释

以下句子定义了侧边注释及其对应的内容：

³And here's my sidenote content.

Result

Here's my sentence and a sidenote ^{3 3}And here's my sidenote content..

Source

Here's my sentence and a sidenote[^sn1].

[^sn1]: And here's my sidenote content.

创建页边注释

页边注释通过在内容块的开头添加 {-} 来定义。以下语法定义了页边注释：

And here's my marginnote content.

Result

Here's my sentence and a marginnote And here's my marginnote content..

Source

Here's my sentence and a marginnote[^mn1].

[^mn1]: {-} And here's my marginnote content.

使用 {margin} 指令的块级页边内容

{margin} 指令允许你创建带有可选标题的块级页边内容。它是 Sphinx {sidebar} 指令的封装，主要通过 CSS 类实现其功能（见下文）。

参见

如果你想要带有编号引用的内联页边内容，请参阅 旁注和边注。

以下是如何使用 {margin} 指令：

Result

Here is my margin content

It is pretty cool!

Source

```{margin} **Here is my margin content**
It is pretty cool!
```

页边图注

你可以配置图表，使其使用页边来放置图注。以下是带有右侧图注的图表。

Source

```{figure} ../images/cool.jpg
---
width: 60%
figclass: margin-caption
alt: My figure text
name: myfig5
---
And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-).
```

Result

图 1 And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-).

可以通过 这个引用 来引用图表。或者使用编号引用，如 图 1。

自定义外边距内容的 CSS 类

您也可以直接在页面元素上添加 CSS 类，以使它们表现得像外边距内容。为此，请在页面上的任何元素上添加 margin CSS类。许多 Sphinx 指令允许您直接添加类。例如，以下是向 {note} 指令添加 margin 类的语法：

Result

备注

This note will be in the margin!

Source

:::{note}
:class: margin
This note will be in the margin!
:::

此方法适用于页面上的大多数元素，但通常最适合用于“父容器”，即作为一组内容的最顶层元素。例如，如果您愿意，也可以将整个图放在外边距中。下面是带有下方标题的图。将在下方添加注释，以创建一些垂直空间，以便更好地查看。

Result

图 2 And here is my figure caption

Source

```{figure} ../images/cool.jpg
---
figclass: margin
alt: My figure text
name: myfig4
---
And here is my figure caption
```

可以通过 And here is my figure caption 引用该图。或者使用编号引用，如 图 2。

页边距中的内容示例

页边距内容可以包括各种内容，例如代码块：

Code blocks in margins

print("here is some python")

Code blocks in margins

print("here is some python")

`````{example} Admonitions and images in the margin
:no-container:
:reverse:

````{margin} **Notes in margins**
```{note}
Wow, a note with an image in a margin!
![](../images/cool.jpg)
```
````

侧边栏

侧边栏与正文在同一行，但允许页面其余部分在其周围流动，而不是移动到右侧页边距。

要添加内容侧边栏，请使用以下语法：

Source

````{sidebar} **My sidebar title**
```{note}
Here is my sidebar content, it is pretty cool!
```
![](../images/cool.jpg)
````

Result

My sidebar title

备注

Here is my sidebar content, it is pretty cool!

注意内容是如何在右侧围绕侧边栏流动的。然而，侧边栏的文本仍然会与你的内容保持对齐。某些类型的元素，例如“注释”块和代码单元格，可能会与侧边栏发生冲突。如果发生这种情况，请尝试改用 {margin}。

全宽内容

全宽内容延伸至右侧页边距，使其在书籍其余内容中更加突出。要在页面中添加全宽内容，请将类 full-width 添加到文档中的任何元素。例如，您可以像这样将 full-width 标签添加到注释元素中：

Source

```{note}
:class: full-width
This content will be full-width
```

Result

备注

This content will be full-width

A note for ipynb users

如果你正在使用 Jupyter Notebook 作为文档的输入，并使用 MyST-NB 扩展，你可以通过在代码单元格中添加 full-width 标签来触发这种行为。

---