一些语法说明

10.6. 一些语法说明#

10.6.1. 图片#

MyST Markdown provides a few different syntaxes for including images in your documents, as explained below.

标准 markdown 语法

![fishy](../images/fun-fish.png)

其中中括号里是图片的描述（caption），小括号里是图片位置，它会被渲染为

fishy

这种方法很简便，但是不能调宽度，对齐等。

MyST 语法

MyST 有专门的语法用来插入图片：

```{image} ../images/fun-fish.png
:alt: fishy
:class: bg-primary mb-1
:width: 200px
:align: center
```

其中 class 用于指定样式，它会被渲染为

{image} ../images/fun-fish.png :alt: fishy :class: bg-primary mb-1 :width: 200px :align: center

Raw HTML 图片

The image syntax described above gives you more customizability, but note that this syntax will not show the image in common Markdown viewers.

要使用 HTML 图片，得先在 _config.yml 中做如下设置：

parse:
  myst_enable_extensions:
    # don't forget to list any other extensions you want enabled,
    # including those that are enabled by default!
    - html_image

HTML images will be parsed like any other image. For example:

<img src="../images/fun-fish.png" alt="fishy" class="bg-primary" width="200px">

will correctly render

Using raw HTML is usually a bad choice, so be careful before doing so!

Figures

MyST Markdown also lets you include figures in your page. Figures are like images, except that they are easier to reference elsewhere in your book, and they include things like captions. To include a figure, use this syntax:

```{figure} ../images/C-3PO_droid.png
---
height: 150px
name: directive-fig
---
Here is my figure caption!
```

which will produce the following:

{figure} ../images/C-3PO_droid.png --- height: 150px name: directive-fig --- Here is my figure caption!

10.6.2. References and Citations#

References allow you to refer to other content in your book or to external content.<br/>
Citations（引用） and bibliographies（参考书目） allow you to cite scholarly work and provide bibliographies that allow readers to follow the references.

References

Cross-references in Jupyter Book usually involve two things:

  1. Create a label for something.

  2. Create a reference with a target.

创建 label

Labels must come just before headers.

(my-label)=
## My header

Some text

This is how you specify a label called my-label that points to the header just below (## My header).

Refer to your label

Now that you’ve created a label, you can refer to it from elsewhere.

Here's some text and [here's my label](my-label).

其中中括号内是 refer 应当显示的 text.

Citations

首先你需要一个 bibtex file 用于存放所需的 citations. 比如说在样书（sample book）中就有 references.bib

# In references.bib
@inproceedings{holdgraf_evidence_2014,
  address = {Brisbane, Australia, Australia},
  title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}},
  booktitle = {International {Conference} on {Cognitive} {Neuroscience}},
  publisher = {Frontiers in Neuroscience},
  author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.},
  year = {2014}
}

然后需要再 _config.yml 中包括进这个 bibtex file:

bibtex_bibfiles:
    - references.bib

In your content, add the following syntax to include a citation:

Here is my nifty citation {cite}`holdgraf_evidence_2014`.

它会被渲染为：

Here is my nifty citation {cite}holdgraf_evidence_2014.

Bibliography

Finally, we’ll generate a bibliography for our citations. Links to this bibliography will automatically be created when you cite something.

点击任一引用时会自动跳转到 bibliography 的相关条目，我们使用如下语句来添加 bibliography:

```{bibliography}
```

它会被渲染为：

目录