> 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/30-how-to-write-in-markdown-on-overleaf.md).
# 如何在 Overleaf 中使用 Markdown 写作
**发布后更新** （2017年5月13日新增）：我们感谢 Vít Novotný，以下这个的作者/维护者 `Markdown` 宏包，感谢他就原始文章写信给我们并提供了一些有帮助的反馈。我们很高兴发布这个更新版本，其中采纳并包含了他的建议。
### 呃，什么？
[Markdown](https://kirkstrobeck.github.io/whatismarkdown.com/) 是一种轻量级标记语言（懂了吧？😉），它让你能够用纯文本和一些 *非常* 简单规则写出内容，然后将其转换为格式化输出，例如 HTML。它在软件开发者和程序员中非常受欢迎，正是因为它简单（顺便说一句，它也非常适合记笔记！）。
例如，要写一份简短的购物清单：
```
# 杂货清单
*记得*在即将到来的[促销](http://acme-marg.com)活动中尽可能多拿一些！
## 食品
- 焗豆
- 意大利面
## 文具
- 书写垫
- 铅笔
```
然后你会得到如下 HTML 输出，使用诸如 [pandoc](http://pandoc.org/):
```html
购物清单
记得在即将到来的促销活动中尽可能多拿一些！
食品
文具
```
既简单又漂亮！你还可以在 Markdown 中找到其他语法 [此处](https://daringfireball.net/projects/markdown/syntax).
### 这对我来说意味着什么？
许多 LaTeX 用户对自己漂亮的 LaTeX 排版文档已经很满意，但还是免不了会对 Markdown 用户有点羡慕——因为，嗯，LaTeX 标记 *可以* 有时会相当冗长。没错，列表们，我们说的就是 *你*...
好消息是，这个出色的新 [`Markdown` LaTeX 宏包](https://ctan.org/pkg/markdown) 允许你在 LaTeX 文档中编写 markdown 语法（也就是更简单的输入），同时仍然得到排版精美的 PDF！你只需要做的就是在 `Markdown` 宏包中加载你的文档，并将你的 Markdown 内容包裹在一个 `Markdown` 环境：
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# 杂货清单
*记得*在即将到来的[促销](http://acme-marg.com)活动中尽可能多拿一些！
## 食品
- 焗豆
- 意大利面
## 文具
- 书写垫
- 铅笔
\end{markdown}
\end{document}
```
或者，如果你更愿意把 Markdown 内容放在一个 `*.md` 文件中：
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}
```
太棒了！这很可能会让开发者类型的人非常高兴，因为他们现在只需复制他们的 `.md` 文档！
### 如果我写 Markdown，还能使用 LaTeX 命令吗？
可以，你仍然可以在你的 Markdown 内容中使用 LaTeX 命令！只需传入 `hybrid` 选项设置为 `Markdown`:
```latex
\usepackage[hybrid]{markdown}
...
- 书写垫（封面上印着大大的 $E=mc^2$ 的那种）
```
### 我该如何使用诸如 '#' 和 '\_'（下划线）这样的字面字符？
#### 输入一个 '#'
你不能在 *该 `Markdown` 环境*中输入 '#' 字符。甚至连 `\#` 也不行。你需要定义一个类似这样的命令： `\newcommand{\texthash}{\#}`，然后使用 `\texthash` 到你的 `Markdown` 环境。同样地，对于下划线，尤其是当同一行上有多个时，例如 `$y = m_1 + n_2$`。有时，结束当前 `Markdown` 环境，并在普通 LaTeX 模式下写有问题的行，然后再开始另一个 `Markdown` 环境中。
#### 输入 '\_'（下划线）和 '\`'（反引号）
**更新** （2017年5月13日新增）：自 `Markdown` 2.5 版本起，你可以设置 `underscores = false` 和 `codeSpans = false` 来禁用下划线和反引号。这使得你可以在混合模式下写数学下标和引号，而无需转义。我们已经有星号用于强调，所以真正失去的只有行内代码示例。感谢 Vít 提供这个提示！
#### 应避免的环境……
虽然你可以使用反引号来写行内原文，或者将该行缩进四个空格来写一个原文块，但不要使用 `lstlisting` 也不要使用 `minted` LaTeX 环境嵌套在 `Markdown` 环境中。千万不要这么做。
#### 在 markdown 环境中使用 HTML
不，不能在 LaTeX `Markdown` 环境中使用 HTML（尽管这在常规 Markdown 中很常见）。抱歉。
**更新** （2017年5月13日新增）：截至 `Markdown` v2.3，出现了一个 `html` 选项：如果 markdown 内容中包含 HTML 标签，它不会原样显示这些标签，不过它也不会实际格式化标签内容——也就是说， `你好！` 只会以普通字重显示你好！。但像 `©` 这样的 HTML 实体会被渲染为 ©。感谢 Vít 指出这一点。
### 推荐的 markdown 宏包选项
其中一组 `Markdown` 你可能会觉得有用的宏包选项是：
```latex
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
```
这些选项启用了
* 脚注 Markdown 语法（例如 `[^1]`);
* 定义列表，以及 `#` 用于有序列表；
* “正确”的省略号（…）。
这里有一个 [完整示例](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) 在 Overleaf 示例库中，这里还有 [另一个](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### 超链接和脚注：怎么做？
在 Overleaf 示例中，超链接是一个脚注。我要怎样才能让它成为一个 hyperref 超链接？
`Markdown` 是可自定义的，因此你可以定义不同元素应如何渲染。将这些添加到你的导言区即可实现：
```latex
\markdownSetup{renderers={
link = {\href{#2}{#1}}
}}
```
**更新** （2017年5月13日新增）： `rendererPrototypes` 在最初版本中使用过。一般用户建议使用 `renderers` 来定义自己的内容，因为 `rendererPrototypes` 是供宏包创建者提供默认值的。如果你修改 `rendererPrototypes`，你就有可能让另一个宏包覆盖你的设置。感谢 Vít 指出这一点！
### 包含图片（2022年11月8日更新）
* **注意**：下一个示例使用了一个图形文件（`example-image.pdf`）由 `mwe` 宏包提供。这些图形文件由 TeX Live 分发，因此存储在 Overleaf 的服务器上，并可作为图像占位符使用，例如下面的示例。
可以通过编写以下格式的标记在 markdown 中包含图像：
```latex
```
希望参数名称 `alt-text`, `file-name` 和 `"图片说明"` 说明它们的作用。下面是一个演示示例：
```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
% The mwe package provides example images. Loading it is
% not essential because those images are in LaTeX's search path.
% Here, we load it for clarity in this example.
\usepackage{mwe}
\begin{document}
\begin{markdown}
这个示例展示了如何导入图形文件。这里我们使用的是一个
由 `mwe` 宏包提供的示例图像。
% Use \setkeys{Gin} if you need to change an image's display size
\setkeys{Gin}{width=.5\linewidth}
\end{markdown}
\end{document}
```
[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)
此示例生成如下输出：
#### 关于图像宽度的说明
和大多数宏包一样， `Markdown` 会加载其他宏包，包括 [`keyval`](https://ctan.org/pkg/keyval?lang=en) 和 [`graphicx`](https://ctan.org/pkg/graphicx?lang=en)，以便使用它们提供的命令和功能。这里，图像宽度是通过 `\setkeys` 命令设置的，该命令由 `keyvals`. `Gin` 是由……定义的一“族”键， `graphicx` 宏包。
* **注意**：因为这里使用了一个 LaTeX 命令， `\setkeys`， *在* 该 `Markdown` 环境中， `hybrid` 需要 markdown 宏包的该选项。
#### 更改浮动体放置标识符（更高级）
用于插入图片的 markdown 语法不能让你直接指定浮动体放置标识符，但你可以通过重新定义图片的渲染方式来调整它们：
```latex
\markdownSetup{renderers={
image = {\begin{figure}[hbt!]
\centering
\includegraphics{#3}%
\ifx\empty#4\empty\else
\caption{#4}%
\fi
\end{figure}}
}}
```
更多信息请参阅 [markdown 文档](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### 你能在 LaTeX 中使用 markdown 来创建表格吗？😀
很遗憾，不可以。表格仅在 [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) 中受支持，而 LaTeX `Markdown` 宏包目前尚不支持它。
**更新** （2017年5月13日新增）：根据 Vít 的提示，可以使用 `contentBlocks` 自版本 2.4 起的语法扩展，或者调整 `inputFencedCode` 渲染器，来快速把一些 CSV 风格的文本转换成表格。
### 还有更多 markdown 宏包的好东西……？
正如前面提到的，它是一个很棒的记笔记方式，而当它与一些不错的 LaTeX 文档类或宏包配置结合时，甚至能让你在一堂课结束时就拥有一本漂亮的笔记本。例如，你可以把它和 [Tufte 类](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}
```
而这种短小简洁的语法让写列表变得更加方便，这意味着我们现在有了一种 *真正快速的* 编写 [Beamer 演示文稿](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) 和 [海报](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
尽情享受吧！
---
# 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/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`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.