特殊内容块
Contents
特殊内容块#
有几个内容块是这个主题所特有的。
语录和题记#
这是 sphinx-book-theme 中的引文和题记的样子。
Default markdown quotes
> 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} 指令。下面是一个序言，点击它右边的按钮，显示用于生成该序言的代码：
A basic 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.
你也可以通过添加一个空行，然后添加一个以 -- 开头的行，来为书信添加署名。
Epigraphs with attribution
```{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
Sidenotes and marginnotes#
This theme has support for Tufte-style margin / side notes, with a UX similar to pandoc-sidenote.
Sidenotes are numbered, and behave like footnotes, except they live in the margin and don’t force the reader to jump their eye to the bottom of the page. For example, here is a sidenote1Here’s my sidenote text!. On narrow screens, sidenotes are hidden until a user clicks the number. If you’re on a mobile device, try clicking the sidenote number above.
Marginnotes are not numbered, but behave the same way as sidenotes. On mobile devices you’ll see a symbol that will show the marginnote when clicked This is a margin note. Notice there isn’t a number preceding the note.. For example, there’s a marginnote in the previous sentence, and you should see a symbol show to display it on mobile screens.
参见
Sidenotes and marginnotes are inline content - you cannot use block-level content inside of these notes. If you’d like to use block-level content in the margins, see Block margin content with the {margin} directive.
Activate sidenotes and marginnotes#
The theme activates sidenotes and marginnotes by over-riding footnote syntax to instead exist in the margin.
To convert your footnotes to instead be sidenotes/marginnotes, use this configuration:
html_theme_options = {
...
"use_sidenotes": True,
...
}
This will turn your footnotes into sidenotes or marginnotes.
Create a sidenote#
The following sentence defines a sidenote and its respective content:
3And here’s my sidenote content.Result
Here’s my sentence and a sidenote3And here’s my sidenote content..
Source
Here's my sentence and a sidenote[^sn1].
[^sn1]: And here's my sidenote content.
Create a marginnote#
Marginnotes are defined by adding {-} at the beginning of the content block.
The following syntax defines a marginnote:
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.
Block margin content with the {margin} directive#
The {margin} directive allows you to create block-level margin content with an optional title.
It is a wrapper around the Sphinx {sidebar} directive, and largely does its magic via CSS classes (see below).
参见
If you’d like in-line margin content with numbered references, see Sidenotes and marginnotes.
下面是如何使用 {margin} 指令的：
Result
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 这是我的图片说明，如果你看左边，你可以看到 COOL 是大红字。但你可能已经注意到了，其实我只是占用了一些空间，看看当标题真的很长时，边距是什么样子的：:-)。#
CSS classes for custom margin content#
你也可以直接给你的页面上的元素添加 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!
:::
This works for most elements on the page, but in general this works best for “parent containers” that are the top-most element of a bundle of content. For example, you can also put the whole figure in the margin if you like. Here is a figure with a caption below. We’ll add a note below to create some vertical space to see better.
Result
图 2 这是我的图片说明#
Source
```{figure} images/cool.jpg
---
figclass: margin
alt: My figure text
name: myfig4
---
And here is my figure caption
```
Content examples in the margin#
Margin content can include all kinds of things, such as code blocks:
`````{example} Admonitions and images in the margin
:no-container:
:reverse:
````{margin} **Notes in margins**
```{note}
Wow, a note with an image in a margin!
```
````
全宽内容#
全宽内容延伸到右边的空白处，使它在你的书的其他内容中脱颖而出。要在你的页面上添加全宽内容，请在文档中的任何元素上添加 full-width 类。例如，你可以像这样给笔记元素添加一个 full-width 标签：
Source
```{note}
:class: full-width
This content will be full-width
```
Result
备注
这个内容将是全宽的
给 ipynb 用户的说明
如果你使用 MyST-NB 插件 的 Jupyter 笔记本作为文档的输入，你可以通过在代码单元中添加 full-width 标签来触发这一行为。