> 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-tw/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/98672d99d20d0282a1073446650ceeb3020524a6)

## 使用內嵌 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/91aca3a88d66946a7cc5526d29fce3d91dd03b09)

## 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}
```

[在 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/544a7dde582b1a1ba12859c3231aa596783d8496)

#### 使用圍欄式程式碼區塊

圍欄式程式碼區塊可透過撰寫以下其中一種方式建立

* 三個反引號（` ``` `），或
* 三個波浪號（`~~~`)

在程式碼區塊前後的行中。使用這種方法您不必縮排任何一行，但您需要使用 `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}
````

[在 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/f3eb4800a1151b3470c92c5e686ff72f264fdb7b)

#### 語法高亮

圍欄式程式碼區塊可透過在第一組反引號（`` ` ``）後面寫上語言名稱來支援語法高亮。舉例來說，下方區塊會藉由將第一組反引號寫成以下形式來辨識為 Javascript： ` ``` 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}
````

[在 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/476435ba068d31de3cf186382b34ed0e6fcbbeb0)

### 清單

前面的範例 [示範如何建立無序清單](#using-inline-markdown) 在 Markdown 中使用 `*` 字元。若使用 `#` 字元，則可建立有序清單，只要 `hashEnumerators` 已指定該選項：

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

也可以建立巢狀清單，如下一個範例所示：

```latex
\documentclass{article}
\usepackage[hashEnumerators]{markdown}
\begin{document}
\begin{markdown}
以下是一個包含巢狀清單的編號清單：

#. 首先，取得以下材料：

      * 胡蘿蔔
      * 芹菜
      * 扁豆

#. 將一些水煮沸。

#. 把所有東西倒進鍋裡，然後依照這個演算法：

        找木湯匙
        打開鍋蓋
        攪拌
        蓋上鍋蓋
        把木湯匙不穩地平衡放在鍋把上
        等待 10 分鐘
        跳回第一步（或完成後關閉爐火）

    不要碰到木湯匙，否則它會掉下來。
\end{markdown}
\end{document}
```

[在 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/8d33182c7838dade1a7967759d25e65b83668009)

### 在 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}
```

[在 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/0b5618df4a4d1220e9a5eea4ed45478731098fef)

### 加入圖片

* **注意**: 下一個範例使用一個圖形檔案（`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/d3db22cef6f60c7bea1dd477fa3e4966af6ffb46)

#### 關於圖片寬度的說明

和大多數套件一樣， `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 套件的選項是必要的。

## 延伸閱讀

Overleaf 已發表其他關於使用 Markdown 的文章：

* [如何在 Overleaf 上使用 Markdown 寫作](/latex/zh-tw/shen-ru-wen-zhang/30-how-to-write-in-markdown-on-overleaf.md)
* [Markdown 轉 LaTeX 與樣式](/latex/zh-tw/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-tw/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.