> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/zh-cn/shen-ru-wen-zhang/32-markdown-into-latex-with-style.md).

# 带样式的 Markdown 转 LaTeX

**发表后更新** （2017年5月13日）：我们非常感谢 Vít Novotný，他是该 `markdown` 包的作者/维护者，曾就原文向我们提供了有帮助的反馈。我们很高兴发布这个更新版本，其中采纳并包含了他的建议。

### 引言

不久前，我们为 [`markdown 包`](http://www.ctan.org/pkg/markdown) 的发布而欢欣鼓舞；它使得能够在 LaTeX 文档中编写 markdown 语法——我们还写了一篇名为 [如何在 Overleaf 中使用 Markdown 写作](/latex/zh-cn/shen-ru-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md) 的文章来庆祝，其目的是展示一些受支持的语法。

**请记住**：你需要编译你的 `.tex` 文件，并使用 `--shell-escape` 选项，才能使其在本地 LaTeX 安装中正常工作——Overleaf 会自动为你完成这一点。请注意，大多数期刊投稿门户并不启用 `--shell-escape`——除非你只被允许上传稿件的输出 PDF，否则当包含 markdown 的 LaTeX 文件由出版商的投稿系统处理时，可能无法成功编译。

早先那篇 [文章](/latex/zh-cn/shen-ru-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md) 中提到的一个想法是，markdown 与 LaTeX 的结合能够很好地将内容与样式分离。作者（尤其是已经熟悉 markdown 的作者）将拥有更简洁的语法可用（当然也有一些注意事项），同时仍然可以使用 LaTeX 的所有宏包和模板来处理样式与排版。这一 [文章](/latex/zh-cn/shen-ru-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md) 展示了一些在 [Beamer 演示文稿](https://www.overleaf.com/read/dnrwnjrpjjhw) 和 [海报](https://www.overleaf.com/read/jtbgmmgqrqmh)中使用 markdown 的示例：今天我们要看看更多有趣而令人兴奋的样式可能性！

### 在样式化 LaTeX 模板中使用 markdown

除了上面的示例之外，你几乎可以在所有模板中使用 markdown。这里有几个快速示例：

* 该 [Legrange 橙色书籍](https://www.overleaf.com/latex/templates/the-legrand-orange-book-template-english/jtctyfmnpppc) 模板
* 该 [受 Tufte 启发的讲义](https://www.overleaf.com/latex/templates/handout-design-inspired-by-edward-tufte/dtsbhhkvghzz) 模板
* 这 [非常不错的文章模板](https://www.overleaf.com/read/xfsrpsmdtqvt) 由 Thiago 提供

你可能会注意到，其中两个是文章模板，另一个是书籍模板。 [`markdown 包`](http://www.ctan.org/pkg/markdown) 会检测 `\chapter` 命令是否可在某个特定的 LaTeX 文档中使用，并会将一级标题 `markdown` 行渲染为 `\chapter` 或 `\section` 相应的样式。

### 超快速讲义：markdown + pocketmod

从我第一次了解到 markdown 起，我就觉得它是一种快速而方便的记笔记方式：它很像我会在纸片或便利贴上匆匆写下笔记的方式——尤其是带项目符号和编号列表的语法。2015 年我第一次创建 [PocketMod 模板](https://www.overleaf.com/read/nqbhpnrkskrx) 时，我就渴望能在 LaTeX 中使用 markdown，这样我就可以创建 PocketMod *与* markdown，因为我觉得这……很合适。在小小的折叠小册子上用简单语法记笔记，但排版又很漂亮——有些人把 PocketMod 称为“zine”，因为它们是可以用一张 A4 纸做成的 8 页小册子。

事实证明这确实可行！这让快速制作 [每周计划小册子](https://www.overleaf.com/read/zfzcxygqwqsq) 或者一个小的 [图画故事书](https://www.overleaf.com/read/rppnsfgnrhsf)变得相当容易。是的，看着用她自己的画做成的故事书，我女儿确实会被逗乐……不过也就 10 分钟！ [`markdown 包`](http://www.ctan.org/pkg/markdown) 允许你自定义每种 markdown 语法如何渲染为 LaTeX，所以我重新定义了标准的 `![](img_file "caption")` 语法，把标题放在图像文件下方（不带任何“Figure”前缀或编号），然后插入分页符。这样制作图画书就更容易了。下面是一段演示如何折叠小册子的视频：

{% embed url="<https://www.youtube.com/embed/IAb31rIeGZo>" %}

### 简单食谱小册子

仔细想想，食谱其实就是由列表组成的：配料列表、准备或烹饪步骤列表，也许还有备注列表（烹饪时间、份数等）。所以，与其这样写：

```latex
\begin{enumerate}
\item 第一步做这个
\item 然后做那个
...
\end{enumerate}
```

我当然更希望能够这样写：

```
#. 第一步做这个
#. 然后做那个
```

配料部分也同样如此：

```
- 2 个鸡蛋
- 一撮盐
```

因此，为了轻松快速地制作食谱，我们可以这样写：

```
# 炒鸡蛋

烹饪时间
：5 分钟

可供
: 1

## 配料
- 4 个鸡蛋
- 1 茶匙黄油
- 1/4 杯牛奶
- 盐、胡椒（适量）

## 步骤

#. 打散鸡蛋、牛奶……
#. 在平底锅中加热黄油……
#. ...
```

嗯，这看起来很有希望。Overleaf 的几位同事（以及我们的家人）贡献了自己最喜欢的快捷食谱（非常适合初次下厨的人），而我顺手做了一个（抱歉这个双关） [快速食谱模板](https://www.overleaf.com/read/gscqdhnwzsfg) ，你可以用 markdown 写它 *和* 并把它做成一个小册子。

[![A recipe booklet produced on Overleaf using markdown](/files/aa82566a348ea2724049183cfc1ff5834a7afa2b)](https://www.overleaf.com/read/gscqdhnwzsfg)

现在又到了另一部分乐趣。其底层仍然是 LaTeX，所以我们可以继续使用常见的 LaTeX 小技巧来为各个元素——章节标题、项目列表、字体等等——进行样式设置。就在这时，我有些玩过头了，并提出了 *三个* 针对 `simple-recipe` 类的“主题”！

### 额外内容 1：使用 markdown 包时的一些注意事项

* SyncTeX 不会完全正常工作。在 Overleaf 上，这意味着“预览中的位置”和“在预览中点击跳转到源代码”这两个操作在 `markdown` 区域中将无法工作。
* `\\` 失去了其通常含义：常见的“两个空格后跟一个换行” `markdown` 技巧在这里不起作用，因为尾随空格会被 Lua 解析器移除，如 [`markdown` 包文档](http://texdoc.net/pkg/markdown). `\newline` 中所述。不过，
* 要小心同一行中出现多个下划线字符——如果：这可能会成为问题：

  * 你的公式里有很多下标（提示：在这种情况下跳出 `markdown` 环境）；
  * 你喜欢在 BibTeX 键中使用下划线。

  你可以设置 `underscores=false` ，并配合最新的 `markdown 包` 文件来让下标下划线正常工作，但它仍然无法处理 BibTeX 键中的下划线。

  **更新** （2017年5月13日）：BibTeX 键中的下划线将可在 `markdown` v2.5.2 及之后版本中正常工作——谢谢你，Vít！
* 要显示字面意义上的井号字符会有些困难，因为连 `\#` 也不行！我通常会定义一个新命令并改用它。

### 额外内容 2：更新后的 markdown 包中的新功能

`markdown` v2.4 及之后版本增加了对一些非常不错语法的支持：

* **行内脚注语法**: `...^[这是脚注]` （需要 `inlineFootnotes` 选项）
* **引文：**`[@smith1990]` （需要 `引文` 选项；同时也要留意你 BibTeX 键中的下划线！）
* **围栏代码**：你可以使用波浪线 `~` 或反引号 `` ` `` 作为围栏。

```
~~~~
int main() {
  cout << "Hello world!";
  return 0;
}

~~~~
```

如果你想使用这些新功能，请务必上传以下文件的更新版本： `markdown.lua`, `markdown.tex` 和 `markdown.sty` 到你的项目中——或者你也可以直接从 [这个模板](https://www.overleaf.com/read/whdrnpcpnwrm).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/zh-cn/shen-ru-wen-zhang/32-markdown-into-latex-with-style.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.