> 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/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 標籤，將不會逐字顯示它們，不過它也不會實際格式化標籤內容——也就是說， `哈囉！` 只會以一般字重顯示 Hello!。但像 `©` 會被渲染為 ©。感謝 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/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 套件的選項是必要的。 #### 變更浮動體放置識別符號（較進階） 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://overleaf-pro.ayaka.space/latex/zh-tw/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.