> 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/zhi-shi-ku/166-writing-markdown-in-latex-documents.md).

# 在 LaTeX 文档中编写 Markdown

## 引言

要在 LaTeX 文档中使用 markdown，你需要加载 [`markdown` 宏包](https://www.ctan.org/pkg/markdown) 到文档导言区中：

```latex
\usepackage[settings]{markdown}
```

其中 `[settings]` 是一个 *可选的* 用于配置或启用特定宏包功能的一组参数。请参阅 `markdown` 宏包 [文档](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html) 以获取 [宏包参数（选项）的说明](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html#options).

本文将简要介绍这两种 *行内* markdown——直接在文档中编写——以及导入 *external* 文本文件中包含的 markdown。

* **提示说明**：通常，在 LaTeX 文档中使用 markdown 应被视为一种补充且方便的方式，用于编写文档内容的某些元素，而不是一种可完全替代 LaTeX 本身的语法。

## 使用外部 markdown 文件

使用命令

```latex
\markdownInput{filename}
```

来包含 markdown 文件 `filename`.

下面的示例插入了一个名为 `example.md`的文件。使用代码列表下方的链接将它们作为 Overleaf 项目打开：

**`main.tex`**

```latex
\documentclass{article}
\title{使用 markdown 宏包}
\usepackage[smartEllipses]{markdown}
\begin{document}

\markdownInput{example.md}

\end{document}
```

**`example.md`**

```latex
%% example.md

# 我是一个 markdown 文件。

而且我可以做 *强调*。
## 带有二级标题

> 引用块是
> 这样写的。
>
> 它们可以跨越多个段落，
> 如果你愿意的话。

使用 3 个连字符表示长破折号。使用 2 个连字符表示
范围（例如，“它都在第 12--14 章中”）。
三个点号 ... 将被转换为省略号
（前提是你在导言区中包含 smartEllipses 选项
）。支持 Unicode。
```

 [将这些文件作为 Overleaf 项目打开。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name\[]=main.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Ctitle%7BUsing+the+markdown+package%7D%0A%5Cusepackage%5BsmartEllipses%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5CmarkdownInput%7Bexample.md%7D%0A%0A%5Cend%7Bdocument%7D\&snip_name\[]=example.md\&snip\[]=%25%25+example.md%0A%0A%23+I%27m+a+markdown+file.%0A%0AAnd+I+can+do+%2Aemphasis%2A.%0A%23%23+With+sub-headers%0A%0A%3E+Block+quotes+are%0A%3E+written+like+so.%0A%3E%0A%3E+They+can+span+multiple+paragraphs%2C%0A%3E+if+you+like.%0A%0AUse+3+dashes+for+an+em-dash.+Use+2+dashes+for+%0Aranges+%28ex.%2C+%22it%27s+all+in+chapters+12--14%22%29.+%0AThree+dots+...+will+be+converted+to+an+ellipsis+%0A%28provided+you+include+the+smartEllipses+option+%0Ain+your+preamble%29.+Unicode+is+supported.\&main_document=main.tex)

此示例生成以下输出：

![显示 markdown 宏包输出的图示](/files/a1aed4e8fcd886dbcb698c162b0218e865ef5268)

## 使用行内 markdown

使用 `markdown` 环境：

```latex
\begin{markdown}
...你的 markdown
写在这里...
\end{markdown}
```

来编写行内 markdown，如下一个示例所示：

```latex
\documentclass{article}
\usepackage[hashEnumerators,smartEllipses]{markdown}
\begin{document}

行内 markdown 用法：

\begin{markdown}
一个 h1 标题
============

段落之间用空行分隔。

第二段。*斜体*、**粗体**和 `等宽字体`。项目列表
如下所示：

* 这一项
* 那一项
* 另一项

> 引用块是
> 这样写的。
>
> 它们可以跨越多个段落，
> 如果你愿意的话。

一个 h2 标题
------------

这里有一个编号列表（如果你想使用井号，请使用 `hashEnumerators` 选项）：

#. 第一项
#. 第二项
#. 第三项

\end{markdown}
\end{document}
```

 [在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BhashEnumerators%2CsmartEllipses%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0AUsing+inline+markdown%3A%0A%0A%5Cbegin%7Bmarkdown%7D%0AAn+h1+header%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AParagraphs+are+separated+by+a+blank+line.+%0A%0A2nd+paragraph.+%2AItalic%2A%2C+%2A%2Abold%2A%2A%2C+and+%60monospace%60.+Itemized+lists%0Alook+like%3A%0A%0A%2A+this+one%0A%2A+that+one%0A%2A+the+other+one%0A%0A%3E+Block+quotes+are%0A%3E+written+like+so.%0A%3E%0A%3E+They+can+span+multiple+paragraphs%2C%0A%3E+if+you+like.%0A%0AAn+h2+header%0A------------%0A%0AHere%27s+a+numbered+list+%28use+%60hashEnumerators%60+option+if+you+want+to+use+hashes%29%3A%0A%0A%23.+first+item%0A%23.+second+item%0A%23.+third+item%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![在 Overleaf 中排版的行内 markdown 示例](/files/4606c85a6910490f5862d6f808ca0c5b8762836d)

## markdown 宏包的功能和选项

这里我们将探讨一些 [功能和选项](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html) 由该 `markdown` 宏包提供。

### 在 markdown 中包含代码

在 markdown 中显示代码片段（代码块）有两种机制：

* 将代码块的每一行至少缩进四个空格或一个制表符，或者
* 使用所谓的 [围栏代码块](#using-fenced-code-blocks)

#### 使用缩进显示代码块

下面的示例在每行代码开头使用了 4 个或更多空格字符——有些行根据所需缩进大小使用了 6、8 或 10 个空格字符：

```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
这里有一些代码片段，它们至少缩进了 4 个空格字符。
\vspace{6mm}

\begin{markdown}

这里是一段 C 代码：

    /* 让我迭代…… */

    int i;
    for(i=0; i<10; i++)
    {
      do-something(i)
    }

这里有一些 HTML：

    <html>
      <head>
        <title>页面标题</title>
      </head>
      <body>
        <h1>这是一个标题</h1>
          <p>这是一个段落。</p>
      </body>
    </html>

\end{markdown}
\end{document}
```

&#x20;[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+code+snippets\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0AHere+are+some+code+fragments+indented+by+at+least+4+space+characters.%0A%5Cvspace%7B6mm%7D%0A%0A%5Cbegin%7Bmarkdown%7D%0A%0AHere+is+a+fragment+of+C%3A%0A%0A++++%2F%2A+Let+me+iterate+...+%2A%2F%0A%0A++++int+i%3B%0A++++for%28i%3D0%3B+i%3C10%3B+i%2B%2B%29%0A++++%7B%0A++++++do-something%28i%29%0A++++%7D%0A%0AHere+is+some+HTML%3A%0A%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![通过 markdown 排版代码的示例](/files/79cd99366a2ec5f33ac15341209bf40c3e52beec)

#### 使用围栏代码块

通过编写以下任一内容即可创建围栏代码块

* 三个反引号（` ``` `），或者
* 三个波浪号（`~~~`)

在代码块前后所在的行中。使用这种方法，你不必缩进任何行，但你确实需要在 `fencedCode` 选项中在导言区启用：

```latex
\usepackage[fencedCode]{markdown}
```

下面是一个使用 3 个反引号（` ``` `):

````latex
\documentclass{article}
\usepackage[fencedCode]{markdown}
\begin{document}
\begin{markdown}

```
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```

```
    <html>
      <head>
        <title>页面标题</title>
      </head>
      <body>
        <h1>这是一个标题</h1>
          <p>这是一个段落。</p>
      </body>
    </html>
```
\end{markdown}
\end{document}
````

&#x20;[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+fenced+code+blocks\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BfencedCode%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0A%0A%60%60%60%0Aif+%28a+%3E+3%29+%7B%0A++++moveShip%285+%2A+gravity%2C+DOWN%29%3B%0A%7D%0A%60%60%60%0A%0A%60%60%60%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%60%60%60%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![使用 markdown LaTeX 宏包的围栏代码块](/files/11a9af3cb94f563c9c0d537690d667d69abc7bc4)

#### 语法高亮

围栏代码块支持语法高亮，只需在第一组反引号后写上语言名称（`` ` ``）。例如，下面的代码块通过将第一组反引号写成 ` ``` js `:

````latex
``` js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```
````

对于 LaTeX， `minted` 宏包可用于语法高亮，如下一个包含一些 Javascript（` ``` js `）和 HTML（` ``` html `):

````latex
\documentclass{article}
\usepackage{minted}
\usepackage[fencedCode]{markdown}
\begin{document}
\begin{markdown}

``` js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```

``` html
    <html>
      <head>
        <title>页面标题</title>
      </head>
      <body>
        <h1>这是一个标题</h1>
          <p>这是一个段落。</p>
      </body>
    </html>
```
\end{markdown}
\end{document}
````

&#x20;[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+fenced+code+blocks\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bminted%7D%0A%5Cusepackage%5BfencedCode%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0A%0A%60%60%60+js%0Aif+%28a+%3E+3%29+%7B%0A++++moveShip%285+%2A+gravity%2C+DOWN%29%3B%0A%7D%0A%60%60%60%0A%0A%60%60%60+html%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%60%60%60%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![使用 minted 和 markdown 的语法高亮](/files/7e6f94273d423d6aaf7bb180b15d9cb936649c63)

### 列表

前面的示例 [演示了如何在 markdown 中创建无序列表](#using-inline-markdown) 使用 `*` 字符。可以使用 `#` 字符创建有序列表，如果 `hashEnumerators` 选项已被指定：

```latex
\usepackage[hashEnumerators]{markdown}
```

还可以创建嵌套列表，如下一个示例所示：

```latex
\documentclass{article}
\usepackage[hashEnumerators]{markdown}
\begin{document}
\begin{markdown}
这里有一个包含嵌套列表的编号列表：

#. 首先，准备这些配料：

      * 胡萝卜
      * 芹菜
      * 小扁豆

#. 将一些水煮沸。

#. 把所有东西倒进锅里，并按照这个算法操作：

        找到木勺
        揭开锅盖
        搅拌
        盖上锅盖
        把木勺勉强平衡地架在锅柄上
        等待 10 分钟
        转到第一步（或者完成后关掉炉灶）

    不要碰到木勺，否则它会掉下来。
\end{markdown}
\end{document}
```

&#x20;[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Creating+a+nested+list+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BhashEnumerators%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AHere+is+a+numbered+list+that+contains+a+nested+list%3A%0A%0A%23.+First%2C+get+these+ingredients%3A%0A%0A++++++%2A+carrots%0A++++++%2A+celery%0A++++++%2A+lentils%0A%0A%23.+Boil+some+water.%0A%0A%23.+Dump+everything+in+the+pot+and+follow+this+algorithm%3A%0A%0A++++++++find+wooden+spoon%0A++++++++uncover+pot%0A++++++++stir%0A++++++++cover+pot%0A++++++++balance+wooden+spoon+precariously+on+pot+handle%0A++++++++wait+10+minutes%0A++++++++goto+first+step+%28or+shut+off+burner+when+done%29%0A%0A++++Do+not+bump+wooden+spoon+or+it+will+fall.%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![使用 LaTeX markdown 宏包创建编号列表](/files/8ecf3054c009846482fa126a7b5606d35ba691c9)

### 在 markdown 中包含 LaTeX

如果你启用 `hybrid` 选项，你就可以在 Markdown 中混用 LaTeX 代码！

```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
\begin{document}

\begin{markdown}
行内数学公式可以这样创建：$\omega = d\phi / dt$。
显示型数学公式可以写成：

\begin{equation}
I = \int \rho R^{2} dV
\end{equation}

\end{markdown}
\end{document}
```

&#x20;[在 Overleaf 中打开此示例。](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+LaTeX+code+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Bmarkdown%7D%0AInline+math+equations+can+be+created+like+this%3A+%24%5Comega+%3D+d%5Cphi+%2F+dt%24.+%0ADisplay+math+can+be+written+as%3A%0A%0A%5Cbegin%7Bequation%7D%0AI+%3D+%5Cint+%5Crho+R%5E%7B2%7D+dV%0A%5Cend%7Bequation%7D%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

此示例生成以下输出：

![在 markdown 中使用 LaTeX 代码](/files/4f00ee605b2318387b5787ec1bb55155921d50bd)

### 包含图片

* **注意**：下一个示例使用了一个图形文件（`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}
```

&#x20;[在 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 宏包的

## 进一步阅读

Overleaf 还发布了其他关于使用 markdown 的文章：

* [如何在 Overleaf 上用 Markdown 写作](/latex/zh-cn/shen-ru-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md)
* [Markdown 进入 LaTeX 并增添样式](/latex/zh-cn/shen-ru-wen-zhang/32-markdown-into-latex-with-style.md)


---

# 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/zhi-shi-ku/166-writing-markdown-in-latex-documents.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.