> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-pro.ayaka.space/latex/zh-cn/shen-du-wen-zhang/32-markdown-into-latex-with-style.md).

# 将 Markdown 以优雅样式转换为 LaTeX

**发布后更新** （2017年5月13日）：我们非常感谢 Vít Novotný，markdown 包的作者/维护者，感谢他就原文撰写了一些有帮助的反馈并写信给我们。我们很高兴发布这一更新版本，其中采纳并纳入了他的建议。 `markdown` 包，感谢他就原文撰写了一些有帮助的反馈并写信给我们。我们很高兴发布这一更新版本，其中采纳并纳入了他的建议。

### 引言

不久前，我们为 [`markdown 包`](http://www.ctan.org/pkg/markdown) 的发布而欢欣鼓舞，它使得可以在 LaTeX 文档中编写 markdown 语法——并用一篇题为 [如何在 Overleaf 上使用 Markdown 写作](/latex/zh-cn/shen-du-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-du-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md) 中提到的一个想法是，markdown 与 LaTeX 的结合能够很好地分离内容与样式。作者（尤其是那些已经熟悉 markdown 的作者）将拥有更简洁的语法可用（但也有一些注意事项），同时仍然可以使用 LaTeX 宏包和模板的全部优势来处理样式和格式。这篇 [前一篇文章](/latex/zh-cn/shen-du-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”，因为它们是 8 页的小册子，可以由一张 A4 纸制作而成。

而事实上，这是可行的！这使得快速制作 [每周计划迷你小册子](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://ayakaleaf-pro.ayaka.space/latex/zh-cn/shen-du-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.