Markdown 轉 PDF

哪些由瀏覽器決定，哪些我們管不到

本頁本身沒有 PDF 引擎。它把你的 Markdown 排版成帶樣式的 HTML，再請瀏覽器列印，而每個現代瀏覽器的列印對話框裡都內建了 PDF 寫入器，這就是為什麼不必安裝任何東西。這筆交易很好懂。

• 你得到的：免安裝、免上傳、不用排隊、沒有大小上限，而且輸出和螢幕上一致。
• 你放棄的：頁面幾何。紙張大小、直橫向、邊界、縮放與背景色都是對話框的設定，我們無法替你決定。

把「背景圖形」打開

這是你能做的最大改善。Chrome 預設是關閉的，關著的時候，程式碼區塊、引用區塊的側線與表格標題底色都會印成一片空白。打開它，紙上就會恢復成預覽的樣子。

把「頁首和頁尾」關掉

Chrome 與 Edge 預設會在邊界印上網頁標題、網址、日期與頁碼。這個開關叫「頁首和頁尾」，位置在「更多設定」裡，Firefox 與 Safari 也有對應的勾選項。想要乾淨的文件就關掉；真的需要頁碼時再留著。

紙張大小、邊界與縮放

先選 A4 或 Letter，再決定方向，最後調邊界。縮放是不起眼的救援手段：從 100% 降到 90%，常常就能把多出來的最後一行拉回前一頁。任何一項改動，對話框裡的預覽都會立刻重畫。

小提醒：設定好之後先印一份試看看，確認沒問題再寄出。瀏覽器會記住你上次用的列印設定，所以第二份之後完全不必再調。

實際範例，以及產生它的設定

以下是一份真的會被列印出來的短文件，包含標題、次標題、表格、項目清單與程式碼區塊：

# Q3 Infrastructure Review

## Summary
Uptime held at 99.98% across all three regions.

| Region | Incidents | Mean recovery |
| :----- | --------: | ------------: |
| eu-west | 3 | 11 min |
| us-east | 1 | 4 min |

## Actions
- Move the staging cluster to the new image
- Add alerting for queue depth > 500

```bash
kubectl rollout restart deploy/api
```

> Full incident notes are in the ops wiki.

印出來是什麼樣子，用了哪些設定

用下面這組設定列印，它會變成整齊的一頁：粗體大標題、有框線且數字靠右的表格、正常的項目清單、等寬字型且帶底色的程式碼區塊，最後是一段內縮的引用。那個圍欄標了 bash，所以關鍵字在預覽和紙上都會上色。原始碼裡的符號一個都不會出現在 PDF 上。

目的地：      另存為 PDF
紙張大小：    A4       （美國用 Letter）
版面配置：    直向     （寬表格改用橫向）
邊界：        預設     （想更密集可選自訂）
縮放：        100%     （90% 可以救回稍微超出的一頁）
背景圖形：    開啟     （保留程式碼區塊底色）
頁首和頁尾：  關閉     （移除網址與日期）

注意大於符號出現在哪個位置

原始碼裡有兩個大於符號，行為完全不同。夾在項目文字中間的那個只是比較運算子，會原樣印出；出現在最後一行行首的那個是 Markdown 的引用標記，會被印成內縮的引用區塊。

位置決定一切，這正是完整 Markdown 指南裡整理的小陷阱之一。如果「標點符號會變成排版」這件事對你還很陌生，什麼是 Markdown 會從頭講起。

所有 Markdown 轉 PDF 路線比較

瀏覽器列印不是唯一的方法，也不永遠是最好的方法。下表誠實比較各種實際可行的選項，包括那些比本頁更強的工具。

什麼時候值得下載 Pandoc

Pandoc 搭配 LaTeX 引擎在四件事上贏得漂亮：每頁自動頁碼、自動產生目錄、交叉參照，以及每週一自動執行同一道指令。這幾項幾乎沒有對手。代價是龐大的安裝檔，還有一套要學的命令列。

什麼時候瀏覽器就夠了

如果只是要一份今天就得寄出、看起來乾淨的文件，瀏覽器路線並不是退而求其次。它更快、完全免費，而且在什麼都不准安裝的公司筆電上照樣能用。

注意：表格最後一列是警語，不是建議。把機密文件上傳到來路不明的轉換器，換不到任何你自己的瀏覽器做不到的事。

常見問題與修法

幾乎每一份不理想的 PDF 都能歸到下面這些狀況。第一組出在列印對話框，第二組出在文件本身，也就是上方預覽其實早就把問題演給你看了。

列印對話框造成的問題

• 程式碼區塊與表格標題印成一片空白。背景圖形是關閉的。在「更多設定」裡打開它，再印一次。
• 頁面邊界出現網址、日期與網頁標題。那是瀏覽器的頁首頁尾，不是你文件的內容。把「頁首和頁尾」取消勾選即可。
• 寬表格右側被裁掉。把版面改成橫向、把縮放降到 85% 或 90%，或直接刪欄。直向 A4 大約六欄就是舒適上限。
• 標題孤零零掉在頁尾。分頁是自動的。在標題上方多加一兩行內容，或在大段落前插入一條水平線，通常就能把它推到下一頁。

文件本身造成的問題

• PDF 裡滿是井字號與星號。你列印的是原始碼而不是排版後的結果。請從排版面板列印，不要從顯示 .md 原始碼的文字編輯器列印。
• 文件少了一半。檢查是不是有未關閉的程式碼圍籬。多出來的三個反引號之後的內容都會被吞進程式碼區塊，所以先讀預覽就能抓到。
• 長網址衝出頁面。裸網址是一個無法斷開的長單字，所以不能換行。寫成 [有文字的連結](https://example.com/very/long/path)，在 PDF 裡依然可以點。
• 一張圖片佔滿整頁。圖片會依渲染尺寸列印。列印前用 <img src="chart.png" width="450"> 限制寬度即可。

這些狀況裡，表格製造的麻煩最多。表格指南說明如何重組塞不下的資料，把格子搬進表格產生器重建，也能很快試出比較窄的版本。

如果檔案是別人寄來的，先用 Markdown 檢視器打開確認讀得順，再從那裡列印。