> 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/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 ![替代文本](文件名 "图片说明") ``` 希望参数名 `替代文本`, `文件名` 和 `“图片说明”` 能够说明它们的作用。下面是一个演示它们的示例： ```latex \documentclass{article} \usepackage[hybrid]{markdown} % mwe 宏包提供示例图像。加载它是 % 非必需的，因为这些图像位于 LaTeX 的搜索路径中。 % 这里，为了清楚起见，我们在示例中加载它。 \usepackage{mwe} \begin{document} \begin{markdown} 这个示例展示了如何导入图形文件。这里我们使用的是 由 `mwe` 宏包提供的示例图像。 % 如果你需要更改图像的显示大小，请使用 \setkeys{Gin} \setkeys{Gin}{width=.5\linewidth} ![这是一段用于描述我的图像的替代文本。](example-image.jpg "由 \texttt{mwe} 宏包提供的示例图像。") \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 中导入图片](/files/0883cd708558061ff26b67991fbb636314f30d4b) #### 关于图像宽度的说明 像大多数宏包一样， `markdown` 会加载其他宏包，包括 [`keyval`](https://ctan.org/pkg/keyval?lang=en) 和 [`graphicx`](https://ctan.org/pkg/graphicx?lang=en)，以使用它们提供的命令和功能。这里，图像宽度是通过 `\setkeys` 命令设置的，该命令由 `keyvals`. `提供。` Gin 是由 `graphicx` 宏包。 * **注意**定义的一组“family”键：因为这里使用了一个 LaTeX 命令 `\setkeys`，即 *，* 该 `markdown` 在 `hybrid` 环境中，因此需要 markdown 宏包的 #### 更改浮动体位置标识符（更高级） 用于插入图形的 markdown 语法不能让你直接指定浮动体位置标识符，但你可以通过重新定义图形的渲染方式来调整它们： ```latex \markdownSetup{renderers={ image = {\begin{figure}[hbt!] \centering \includegraphics{#3}% \ifx\empty#4\empty\else \caption{#4}% 这段文字将使用俄语。这是为了演示西里尔字母在生成的文档中能够正确显示。 \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://overleaf-pro.ayaka.space/latex/zh-cn/shen-ru-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.