【mdout】我開源了一款Markdown轉Pdf命令行工具（一）獲取安裝、使用說明 mdout

以下文檔來自 JabinGP/mdout，如果覺得對你有幫助，不妨點個star鼓勵一下~

mdout

一個Go語言實現的Markdown轉PDF命令行工具，基於headless chrome，簡單、可靠、易安裝、可定製化、易拓展

mdout有何特點

簡單

mdout會根據後綴，自動識別輸入類型

mdout markdown.md
mdout local_html.html
mdout http://www.baidu.com

可靠

mdout可以完整保留你md文件裏的代碼格式，圖片，甚至是數學公式，支持代碼格式語法高亮

電腦不會如人一般等待頁面加載完全再選擇打印，電腦自動執行打印時頁面尚未渲染完全是件非常頭疼的事情，對此，mdout沒有簡單地使用sleep休眠機制去碰運氣，而是實現了一套非常簡單的同步渲染機制，即便是你有1萬行的mathjax數學公式、1萬行的代碼語法高亮要渲染，mdout都能完美的保證你的pdf上不會有任何一個未渲染完成的元素

易安裝

除了chrome，mdout不依賴於其他任何環境，你只需要選擇對於系統的安裝包，下載並解壓即可使用，更爲macOS和linux提供了一鍵安裝腳本，爲windows提供了豐富的圖文教程

可定製化

mdout將每個模板獨立爲主題，並且支持指定輸出html文件，可以很方便地自定義頁面配色，自定義語法高亮配色

易拓展

mdout基於headless chrome，這使得mdout幾乎兼容市面上所有能用於的前端組件，並且mdout將組件歸類爲主題的一部分，你同樣可以輸出html來調試自己的自定義拓展插件

獲取和安裝

由於Github下載速度實在是太過寒酸，只有30KB/s，以下的鏈接全部來自於阿里雲服務器，儘管服務器有帶寬限制，但是應對這個大小的文件還是沒問題的

mdout同時支持windows，linux，macOS，但目前只支持64位的系統

• linux：mdout.linux.x86-64.tar.gz
• macOS：mdout.macOS.x86-64.tar.gz
• windows：mdout_windows_x86-64.zip

mdout已經爲各平臺打包了可執行文件，因此無論何種方式安裝，無非就是下載可執行文件壓縮包後解壓縮，解壓完就可以在mdout所在文件夾使用mdout了

但是爲了命令行使用方便，我更推薦將mdout配置到系統的環境變量中，這樣隨時隨地隨心所欲mdout

適用於老鳥的安裝方式

稍微懂點命令行的使用以下命令即可輕鬆安裝

• linux

  wget http://112.74.177.253:8000/f/edcb3b9e460d4d18ab3f/?dl=1
  tar -xvzf mdout.macOS.x86-64.tar.gz
  sudo mv mdout /usr/local/bin
  mdout install
  

• macOS

  wget http://112.74.177.253:8000/f/100873c74622474da4d9/?dl=1
  tar -xvzf mdout.linux.x86-64.tar.gz
  mv mdout /usr/local/bin
  mdout install
  

腳本安裝

非常感謝Fisher的腳本支持! 自己日用的腳本

linux && macOS推薦使用腳本安裝

• curl方式

  bash -c "$(curl -fsSL https://raw.githubusercontent.com/FisherWY/Shell/master/mdout/install_mdout.sh)"
  

• wget方式

  bash -c "$(wget https://raw.githubusercontent.com/FisherWY/Shell/master/mdout/install_mdout.sh -O -)"
  

手動安裝

點擊前文給出的各版本鏈接，下載成功後解壓縮，你會得到一個mdout可執行文件

windows

1. 點擊下載

   • windows：mdout_windows_x86-64.zip

   下載後使用zip工具解壓縮，解壓後會得到一個mdout.exe可執行文件

2. 放置軟件

   將mdout.exe可執行文件放置平時放軟件的地方，比如D:\mdout這個文件夾裏面，此時你的mdout.exe的全路徑應該是D:\mdout\mdout.exe

3. 設置環境變量

   如果不設置環境變量也可以使用，但是缺點是你需要使用cmd，powershell或者gitbash手動進入D:\mdout才能使用mdout命令

   確定路徑

   
   

設置環境變量，右鍵我的電腦 -> 選擇屬性 -> 左邊的高級系統設置

選擇高級 -> 點擊環境變量

找到下半部分的系統變量，雙擊Path行

在彈出來的窗口選擇新建

填入D:\mdout，然後一定要連續點完三個確定

4. 檢驗

   打開cmd，或者powershell，或者你有gitbash都ok（推薦使用命令行的windows用戶都裝一個gitbash），輸入mdout，看到如下輸出就是成功了

linux

1. 下載linux版本

   點擊下載

   • linux：mdout.linux.x86-64.tar.gz

   下載完成後解壓tar.gz包，解壓後會得到一個mdout可執行文件

2. 將軟件放入可執行文件庫

   打開終端，定位到剛剛下載的文件所在路徑

   cd 你的文件所在文件夾
   

   然後將可執行文件直接移動到/usr/local/bin，linux環境下需要sudo權限

   sudo mv ./mdout /usr/local/bin
   

   輸入密碼就可以了

3. 檢驗是否成功

   輸入mdout --version，看到版本號輸出就是成功了

macOS

1. 下載macOS版本

   點擊下載

   • macOS：mdout.macOS.x86-64.tar.gz

   下載後使用工具解壓tar.gz包，解壓後會得到一個mdout可執行文件

2. 將軟件移動到可執行文件庫

   打開終端，定位到剛剛下載的文件所在路徑

   cd 你的mdout可執行文件所在文件夾
   

   然後將可執行文件直接移動到/usr/local/bin

   mv ./mdout /usr/local/bin
   

3. 檢驗是否成功移動

   輸入mdout --version，看到版本號輸出就是成功了

使用說明

使用前提

mdout依賴於chrome瀏覽器，如果你的電腦已經安裝了新版的chrome瀏覽器，無需更多配置，可以直接運行mdout，如果是舊版的chrome瀏覽器，建議進行升級後使用，如果還未安裝chrome瀏覽器，請安裝後再使用mdout

進行系統初始化

如果你不是使用腳本安裝的，或者腳本安裝不完全成功的，需要手動執行初始化，如果腳本安裝成功，則跳過這一步

mdout依賴於html、css、js的模板，但是模板沒有打包進程序，這是出於自定義化的考慮，執行初始化命令，程序會自動下載需要的文件到配置文件路徑，至於這個路徑在哪，在後面會提到，同時初始化程序執行結束後也會輸出這個路徑，請記住這個路徑，在一些自定義和設置默認值時會使用到

mdout install

最簡單的示例

mdout 文件路徑

文件路徑可以是相對路徑

• 文件在當前目錄

  mdout yourfile.md
  

• 或文件在上級目錄

  mdout ../yourfile.md
  

• 文件路徑也可以是絕對路徑

  mdout /tmp/markdown/yourfile.md
  

幫助文檔

每個命令行程序都有幫助文檔，mdout也不例外

mdout -h
mdout --help

輸入文件類型

mdout支持許多輸入類型，其中最普遍的就是markdown，但同樣也支持html輸入，url輸入，但是注意，如果輸入是url，不要忘記帶上http:://

• markdown

  mdout yourfile.md
  

• html

  mdout yourfile.html
  

• url

  mdout http://www.baidu.com
  

輸出文件類型

對於markdown輸入，mdout支持輸出中間過程的結果。但對於html輸入或者url輸入，它們的唯一輸出結果就是pdf文件了

• markdown輸出pdf（輸出pdf爲默認選項)

  mdout youtfile.md -t pdf  
  mdout yourfile.md
  

• markdown輸出解析後html標籤（這個選項可以得到markdown解析器的解析結果）

  mdout youtfile.md -t tag
  

• markdown輸出經過處理後的完整html文件（常常用來調試主題）

  mdout youtfile.md -t html
  

輸出路徑

mdout支持指定輸出路徑，輸出文件名

你可以使用-o來指定輸出路徑，-o選項同樣做了防呆設計，你可以指定路徑但不帶文件名，mdout會自動識別你輸入文件的文件名和你指定的輸出類型爲你設置名稱，但你同樣可以指定路徑+文件名

• 指定輸出到上級文件夾，自動命名

  mdout yourfile.md -o ../
  

• 指定輸出到/tmp/markdown文件夾，自動命名

  mdout yourfile.md -o /tmp/markdown
  

• 指定輸出到當前文件夾下的badoutput.name

  mdout yourfile.md -o badoutput.name
  

  千萬不要這麼幹，儘管程序不會阻止你設置你的文件名，但是使用規範的後綴是個好習慣。

• 指定輸出到當前文件夾下的goodname.pdf

  mdout yourfile.md -o goodname.pdf
  

指定主題

主題系統只對markdown輸入有效

mdout有着方便易用的主題系統，你可以很自由地自定義主題，mdout預設了三套主題

• 默認主題：default
• 數學公式拓展主題：mathjax
• github風格主題：github

你可以使用-e選項來指定主題

• 指定爲github主題

  mdout yourfile.md -e github
  

• 指定爲數學公式拓展主題

  mdout yourfile.md -e mathjax
  

指定主題後上面提到的輸出選項依舊可用，可以配合-t html選項輸出中間的html文件，這樣可以調試主題效果，詳細的說明將在自定義章節中提到

default和mathjax這兩套主題的配色是一模一樣的，區別在於mathjax是同時支持代碼語法高亮和數學公式渲染的，而default只支持代碼語法高亮

mathjax可以渲染類似這樣的公式

$$\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.$$

我可以將mathjax設爲默認主題並刪除default，但是我沒有那麼做，因爲default可以作爲一個能滿足代碼語法高亮的最小模板 （當然你可能不需要代碼語法高亮，這樣的話default並不能算最小模板） ，基於default模板進行自定義主題將變得非常簡單

至於自定義主題的教程，將在後面提到

打印頁面設置

此項僅在輸出pdf時有效

打印頁面大小設置

mdout預設了8種頁面大小，如果有更多需求，可以在issues提出

• A1 - A5
• Legal
• Letter
• Tabloid

A4爲默認輸出頁面大小，你可以使用-f來指定輸出頁面的大小。同時做了防呆設計，如果你一不小心打成了大寫、小寫，甚至你手抽打成了大小寫混合，都是可以正常識別的。可惜，防呆不防傻，你把字母都打錯了就不能怪我了

• 指定輸出pdf頁面格式爲A4（閒着沒事幹敲着玩）

  mdout yourfile.md -f a4
  

• 指定輸出pdf頁面格式爲Tabloid

  mdout yourfile.md -f tabloid
  

打印頁面方向設置

mdout只支持兩種方向

• 縱向：portrait
• 橫向：landscape

默認打印頁面方向爲縱向，你可以使用-r指令來指定頁面方向格式

• 指定輸出pdf頁面格式爲橫向

  mdout yourfile.md -r landscape
  

打印頁面邊距設置

mdout支持你自定義頁面邊距，以英寸爲單位，默認爲0.4英寸

• 0.4英寸 ≈ 10cm

你可以使用-m指令來指定頁面邊距大小

• 指定打印邊距爲0.2英寸

  mdout yourfile.md -m0.2
  

• 去除頁面邊距

  mdout yourfile.md -m0
  

自定義配置文件

在配置文件安裝目錄下面

• macOS : /Users/你的用戶名/binmdout
• linux: /home/你的用戶名/binmdout
• windows: /c/users/你的用戶名/binmdout

有一個conf.json文件

{
    
    "Out":"",

    "Type":"pdf",

    "Theme":"default",

    "PageFormat":"a4",

    "PageOrientation":"portrait",

    "PageMargin":"0.4"
    
}

包含了以上所有的可選設置，直接修改配置文件可以作爲每次使用mdout的默認參數值

自定義配色

mdout有着簡單易用的主題系統，跟着下面的步驟來，你可以很輕鬆的添加自己的自定義效果

首先打開你的配置文件所在的文件夾

在你的配置包裏面會有一個conf.json文件和theme主題文件夾，其中conf.json文件是用來更改默認參數的，theme存放了你的主題包。

進入theme主題包，你可以看到默認的三個主題包

• default
• mathjax
• github

假設你現在需要自定義你的頁面配色，大小，語法高亮等一切和css有關的內容，並且你想要爲你的主題起名爲mytheme

首先你需要完整複製default的所有內容，到default文件夾所在的目錄並重命名爲mytheme，此時你的theme文件夾裏有四個文件夾：

• default
• mathjax
• github
• mytheme

然後你需要找到一個測試用例比如說這樣一個markdown文件

# 測試標題

## 測試二級標題

### 測試三級標題

#### 測試四級標題

- 測試無序列表1
- 測試無序列表2

1. 測試有序列表1
2. 測試有序列表2

- 測試嵌套
    1. 測試嵌套第二次
        - 測試嵌套第三層


> 測試引用

測試表格

| 標題1 | 標題2 | 標題3 |
| ----- | ---- | ---- |
| 文本1 | 文本2 | 文本3 |
| 文本4 | 文本5 | 文本6 |

**這是加粗的文字**  
*這是傾斜的文字*  
***這是斜體加粗的文字***  
~~這是加刪除線的文字~~

![百度圖片](https://ss0.bdstatic.com/5aV1bjqh_Q23odCf/static/superman/img/logo_top_86d58ae1.png)

[測試超鏈接](https://github.com/JabinGP/mdout)

`測試代碼段高亮`

測試代碼塊高亮

    package main

    import (
        "fmt"
    )

    func main() {
        fmt.Println("Hello Mdout")
    }

緊接着使用mdout yourfile.md -e mytheme -t html來獲取這個markdown文件指定mytheme主題的html輸出結果，用編輯器打開html文件，同時用chrome打開html文件，可以看到，頁面已經自動引入了你剛剛創建的自定義主題包css

<!-- 添加頁面樣式 -->
<link rel="stylesheet" href="/Users/jabin/binmdout/theme/mytheme/css/page.css"/>
<!-- 添加hljs樣式 -->
<link rel="stylesheet" href="/Users/jabin/binmdout/theme/mytheme/css/hljs.css"/>

主題配色分爲兩個文件，一個是頁面配色css文件，一個是代碼高亮的css文件

如果你要修改頁面配色，只需要一邊開着瀏覽器，一遍打開剛剛主題包裏面的
mytheme->css->page.css修改，然後刷新瀏覽器查看結果

或者你想更改語法高亮的配色，由於mdout依賴於hljs，你只需要去hljs官網下載你喜歡的主題包，然後替換mytheme->css->hljs.css裏的內容就可以了

如果你完成了你的主題修改，你可以將剛剛生成的html刪除，或者你想留做自己動手的紀念也是可以的

最後，你可以使用mdout yourfile.md -e mytheme來指定使用你的自定義主題啦，或者你可以在前面提到過的conf.json裏面配置默認使用你的mytheme主題

如果覺得對你有幫助，點個star吧！