ubuntuluoluo

• 用 Markdown + Git 寫文檔真是爽
• MPE 功能很強大，請吃安利
• 用 ditta 畫簡圖輕松愉悅
• 在文檔里插入代碼，隨時驗證自己的想法
• 小型黑科技：制作動態Markdown
• 小型黑科技：使用導入文件功能進行非線性寫作
• 小型黑科技：用 Markdown 寫幻燈片

目標用戶是有寫文檔需求的：策劃、有程序基礎的策劃、有策劃基礎的程序和美術，等等等等。

1. 為什么要用 Markdown 寫文檔

你可能沒聽說過 Markdown，也可能聽說過但沒有習慣用它寫文檔。為了這樣的你！我們首先來說 Markdown 是什么，以及使用它的優點。

Markdown 是一種語言，這種語言的設計思路是：

• 它是一種語言而不是二進制文件格式，可以純文本讀和寫
• 寫的時候盡可能可讀性高（這里隆重對比另一種能純文本寫出格式的語言 LaTeX，雖然二者目的原理都完全不同）
• 在顯示的時候被翻譯成 HTML 顯示，可以很清楚很好看

我們一點一點分析：

首先，Markdown 是一種純文本格式，因此特別適合于Git進行版本控制。

想象一個項目有一個圖文并茂的描述文檔，doc 格式，大小5M。現在我們面臨一個抉擇——是把它放到 Git 上還是網盤上呢？

• 如果放到 Git 上，那么對這個文檔的一丁點更改都會引起一個5M大小的二進制文件的改變。非常浪費。
• 如果放到網盤上，那么這個文檔就會丟失大量的版本信息。重要的改動經常需要手動備份來保留。非常麻煩。

但是用 Markdown 之后，文檔就和代碼一樣是一行行的純文本；圖片之類的資源是外鏈的，不改動圖片本身就不會產生提交。這就大大提高了版本控制的效率。文檔可以像代碼一樣享受版本控制的優點了。

其次，Markdown 在設計時就考慮了可讀性，比如下面這段 Markdown 代碼：

# Sec 1
## Sec 1.1
The *quick* brown fox jumps over the **lazy** dog.
代碼解讀

我覺得對于一個沒接觸過 Markdown 的人來說這段話也不難理解。有一些奇怪的星號，但是不影響我們找到正文。

如果是 LaTeX 的話，要寫成這樣：

\documentclass{article}
\begin{document}
\section{Sec 1}
\subsection{Sec 1.1}
The \emph{quick} brown fox jumps over the {\bfseries lazy} dog.
\end{document}
代碼解讀

放心吧，不加語法高亮初學者連正文和 LaTeX 命令都分不開。

Markdown 的語法之所以如此簡潔，一方面是因為用一些簡單的符號代替了繁雜的格式描述，另一方面是因為 Markdown 本身不關心自己會被如何顯示，而是將顯示的工作交給了預覽工具。（這和 LaTeX 完全相反。）這也是接下來要說的：

第三，Markdown 在顯示時會被預覽工具翻譯為 HTML。

比如# XXX會被翻譯為<h1>XXX</h1>。

這一點非常了不起，因為：

• Markdown 是 HTML 的一種簡寫，在顯示時會『解壓縮』成 HTML。理論上你可以在 Markdown 里直接插入合法的 HTML 塊，他們會成為最終的 HTML 的一部分，做到 Markdown 本身做不到的事。
• Markdown 的格式可以由 CSS 描述
  • 預覽工具或者用戶可以自己決定用什么 CSS 顯示，怎么好看怎么來
  • CSS 這個東西我們都知道，是可以懟天懟地懟空氣的……

很多學術論文都要求用 LaTeX 來寫，因為格式統一優美，不容易出錯。缺點是需要漫長的時間適應和學習 LaTeX，而且經常遇到一個模板就要處理一個模板特有的 bug。 有沒有這樣一種可能，一個 Markdown 預覽工具通過合理的翻譯和合理的 CSS 搭配，來滿足學術論文對于格式的精致要求。 我覺得在今天這是可能的。而且做出來是大功一件。如果你知道有這樣的成果的話請告訴我。

2. 為什么要用VSCode

因為我是微軟信者。

……咳咳，如果你不像我這樣有強迫癥的話，用 Atom、Sublime 之類的文本編輯器是完全可以的。（在VSCode之前我用Sublime寫了很久的 Markdown。）

或者有很多軟件都是專門為編寫 Markdown 而開發，可以試一試。——但我不得不說，專門寫 Markdown 的軟件要么不好，要么收費，要么是在線的。

3. 說起來，為什么要本地寫Markdown

之前我都沒思考過這個問題。寫到剛才那一段的時候我才突然意識到：對啊，現在一些在線的編輯器對 Markdown 的支持已經非常好了。比如有道云筆記或者作業部落的Cmd Markdown。為什么不用這些在線編輯器呢。

答案是沒什么不可以的。考慮到剛才說的兩款在線編輯器甚至有客戶端，甚至解決了沒有網絡時的寫作問題。再考慮到這種成熟的在線服務都有著還不錯的界面，我覺得特別適合剛上手 Markdown 的同學寫文檔。

對我個人而言，選擇本地寫而不是在線寫的原因是：

• 目前我看到的功能最強的 Markdown 工具仍然是 MPE
• 在線文檔編輯是第三方服務，沒有放在自己的服務器上踏實——我們都知道第三方服務其實沒什么不安全的，但就是不踏實
• 有一些私人文檔我們一點都不想它在線
• 放在本地，或者放在 Git 上，可以讓項目文檔隨著項目進展第一時間更新，在團隊合作中避免『我不知道更新了』『我沒看到更新』『我網不好刷新不出來』之類的扯皮

題外話，如果你要用這二者之一的話——Cmd Markdown 的功能十分豐富，甚至接近了本文要說的MPE；而有道云筆記雖然功能少，但更接近最初的 Markdown 設計，更簡明。

4. 特別基本的Markdown語法

基本的 Markdown 語法非常簡單：

• 用#開頭的行表示這是一個標題，如果是二級標題，就兩個#，三級標題就三個#……
• 以*開頭的行，表示這是一個無序列表；而以數字序號開頭的行，表示這是一個有序列表
• 以大于號>開頭的行被認為是一段引用的文字（你可能在一些論壇，或者郵件客戶端里見過這種使用方法）
• 沒有特殊符號開頭的文字就是正文段落。正文段落之間必須有空行。沒有空行的換行會被認為仍然是一段話
• 在任何時候都可以用一對*將內部的文本標為斜體，用一對**將內部的文本標記為粗體
• 前面空四格的段落被認為是代碼段，或者可以認為這個段落內容不會被解釋成任何格式
• 連續敲出你能想到的合適的符號來生成一段分割線，比如***或者---或者___（但是能用---的時候為什么要寫___……）
• 還可以插入鏈接、圖片等等，直接看例子吧。

例子在這里：

sdlfk

這段是最最基礎的 Markdown 語法了。但是似乎還不太夠，缺了什么呢？

對了，缺了表格。

于是又出現了表格的語法。

注意：表格已經不是Markdown的基礎語法了，詳見本文最后一部分的說明。 順帶一提，多年以前如果想在Markdown里插入表格要自己寫 HTML。

即便不安裝任何插件，VSCode 也是支持 Markdown 的語法分析和預覽的。你可以建立一個 .md 的文件然后隨便寫著玩，按 Ctrl+Shift+V 預覽結果。

理論上，沒有空行的文本塊會被解釋為同一段話。所以最佳的寫法是每寫句話回車一次。這樣改動任意一句話對整篇文章的影響都是最小的。 但是這樣不優雅。優雅很重要。 另外，唉……這里有一個悲傷的故事我們放到文末再說。

就像這樣

好了，到此為止 Markdown 的功能已經能夠應付簡單文檔的編寫了。對于游戲開發（或者說軟件開發）來說，以上這些功能足以編寫能夠讓人看懂的文檔。

復雜的內容總是可以通過插入圖片來解決——但是不優雅。雖然在 Word 文檔里插入 Excel 表格這種邪道做法我一向是不支持的，但也不能什么事都用插入圖片解決啊。那我何不用 Photoshop 寫文檔……

如何解決這個不優雅的問題呢？終于到了本文的主角登場了。

---

5. 認識Markdown Preview Enhanced

MPE 是什么？按照它自己的描述：

Markdown Preview Enhanced 是一款為 Atom 以及 Visual Studio Code 編輯器編寫的 超級強大的 Markdown 插件。 這款插件意在讓你擁有飄逸的 Markdown 寫作體驗。

根據我的使用經驗，它沒有自吹自擂。這里是它的文檔，中文的哦。

MPE 的功能過于豐富因此我不想把他們全列出來，對我而言有用、我想安利的功能主要有：

• 目錄
• 批注
• 合并單元格
• 插入 LaTeX 公式
• 用純文本繪圖
• 運行代碼
• 導入和導出
• 制作幻燈片

下面我們分類介紹。在此之前我們先要知道按 Ctrl+K, V 可以叫出功能強大的 MPE 預覽窗口。

6. 對Markdown語法的增強

首先就是目錄，對于長文檔來說，目錄很有必要。

在 MPE 里最簡單的插入目錄的方法就是在單獨的行里使用 [TOC] 標記。這會在當前位置立即插入一個目錄。

但是我經常喜歡另一種方式，在要插入目錄的地方加這么一行：

<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=3 orderedList=false} -->
代碼解讀

第二種方式會直接將生成目錄的 Markdown 文本插入到文中，就像這樣：

看，編號還有bug呢

這樣即使在不支持 [TOC] 標記的編輯器里也可以查看目錄。不過另一方面，使用 [TOC] 標記更簡單，而且現在支持 [TOC] 標記的環境越來越多。而且在 Markdown 里插 HTML 注釋比較難看。所以這是個見仁見智的事情。

注意不管是哪種方法都有辦法設定顯示在目錄里的標題級別。比如可以忽略四級以下的標題，或者忽略一級標題——因為一級標題應該被用來寫文檔標題。

其次是批注。MPE 支持用 == 來高亮一段文字。

文字高亮可以有效提升閱讀體驗。尤其是對于中文來說，粗體和斜體都不是很顯眼，高亮是很實用的。

不僅如此，MPE 還支持 CriticMarkup 進行更復雜的批注：

你可能覺得有了版本控制就不再需要批注。但我覺得批注有助于我們看清一個東西在不同時間段是什么樣子、怎么變成了現在的樣子，是很有用的。有一些信息不應該被隱藏在歷史提交里，而應該讓所有人很清楚地查到。

第三是單元格合并。這一點沒有想象中有用，但偶爾還是會用到的。

最后關于上下標、Emoji啥的就請大家自己嘗試了。

7. 一些讓文檔變得優雅的工具

MPE 內嵌了很多工具，可以將策劃從尷尬的p圖工作中解放出來（投入尷尬的編程工作的懷抱）。

首先是用 LaTeX 寫數學公式。LaTeX 這個東西我腹誹（不，我是明著罵）的地方非常多，但唯有寫數學公式我是很欣賞的。

例子是 MPE 文檔給的，我懶得編了。
咦？但是現在我可以不在 LaTeX 環境下寫公式了，是不是可以更加肆無忌憚噴 LaTeX 了？

其次就是可以用代碼描述一些常用的圖表，比如流程圖、時序圖等等，也支持 Vega 的數學圖表（但支持相當有限）。對我來說最有用的反而是大多數人可能不會用到的 ditta。

用 ditta 繪制一個簡單界面

用 ditta 繪制武器斬味（嗯？？？）

ditta 是一個用字符描述圖形的語言，而且是真正的『所見即所得』——你看到的字符怎么擺放，畫出來的圖形就是什么樣的。看上去像是個玩具。但我覺得這個才是和 Markdown 『易寫易讀』氣質最相符的工具。

ditta 很適合在文檔里插一張簡單的圖畫，描述一個簡單的畫面結構，講清楚自己的想法。大多數情況下我們的文檔里需要的就是這樣的簡圖，而不是特別精美的成品圖（因為它們永遠活在需求里）。從此，我想畫一張圖就不需要打開圖像編輯器畫一張幾十k的圖片，只需要幾十幾百個字符、直接寫在文檔里。然后還有諸如『純文本、易于版本控制』等等一系列的好處我就不贅述了。

ditta 是我非常非常喜歡并推崇的工具，強烈推薦給喜歡純文本寫文檔的大家。

如果代碼沒有被執行，沒有畫出圖的話，請  Ctrl+Shift+P 然后執行 Markdown Preview Enhanced: Run Code Chunk。

8. 在文檔里跑代碼

被三個單撇號（鍵盤左上角那個鍵）包裹的文本塊會被認為是代碼，這和 Github 的習慣是一致的。（注意！這和 Markdown 原始的規則是不同的。）在單撇號后面加上語言的名字就可以享受到對應語言的語法高亮。

可以看到和前面那些繪圖的語句原理是一樣的（請對比一下前面的 ditta）。不同點在于前面的繪圖代碼可以被執行，而我們自己寫的這些代碼默認是不能執行的。畢竟隨便運行代碼是很危險的（尤其是代碼塊還可以被隱藏，十分危險）。如果要運行自己寫的語句的話，需要手動打開設置：

沒變 here

然后，既然可以跑代碼了，那……就已經沒有什么可怕的了。

首先，在策劃文檔里隨時跑一跑數值有助于減輕策劃的睿智程度。

這個傷害公式本身沒有問題，是有用武之地的。但睿智的策劃會在所有的地方都用這個公式。

把代碼隱藏可以得到更好的文檔效果：

只要改代碼里的參數，就可以直接在文檔中顯示結果。是不是很棒？

更妙的是代碼的輸出不僅僅可以是文本，還可以是 HTML 甚至 Markdown。

HTML 輸出就是把輸出的內容直接插入到 Markdown 生成的 HTML 里，無縫成為文檔的一部分：

Markdown 輸出則是將輸出的內容當作 Markdown 源代碼的一部分。這意味著我們獲得了自由度極高的動態 Markdown。

更更妙的是代碼可以分多塊書寫，然后按照一定的順序順次執行。這就使得各種測試調整變得稍微容易了一些。

9. 導入和導出

MPE 可以簡單地把其他文件導入到當前文檔中，語法是：

@import "你的文件"
代碼解讀

簡單明了，鼓掌！

這個東西的實用之處在于：

• 直接插入圖片——不需要之前那么復雜的語法
• 插入很長的代碼——代碼外鏈是個好習慣
• 插入其他 Markdown

插入圖片就不說了。插入代碼會讓文檔變得清爽許多：

i am here

test.lua 是個200多行的大文件，全寫在文檔內難以接受。

插入 Markdown 很有意思。除了把多個小文檔合并成一個大文檔這種無腦的用法之外，我覺得最有潛力的用法是——非線性寫作啊！

如果我們把一些小文件當作卡片的話，善用導入文件功能就可以實現類似 Scrivener 的功能了。雖然用戶體驗上相差甚遠，但是免費啊。

導出文件比導入文件還好理解：

• 首先在預覽窗口里右鍵，選擇 Open in Browser
• 在瀏覽器里打印為 PDF……
• ……完成

你可能會說：我的老板需要我給他一個 doc 格式的文檔。嗯，如果你不是正在申請著作權的話，你的老板非要用 doc 而不是 pdf 文檔基本上只有一種可能——他想背著你修改你的文檔。你應該辱罵他。

如果你不想辱罵他的話，MPE 也是可以導出 doc 文檔的，這個請查閱 MPE 的文檔吧，因為我沒嘗試過所以就不舉例子了。

10. 幻燈片

到上面為止，對我個人而言已經足以應付日常的文檔工作了。

但是還有一種情況，就是要把自己的想法展示給別人。雖然我是覺得打開 A4 大小的 pdf 直接給人講也不錯，不過如果搞個幻燈片不是更讓人開心嘛。

非常好笑的是 MPE 還支持用 Markdown （當然是增強版的）寫幻燈片。

我覺得比起『真厲害』，這個功能更傾向于好笑啊哈哈哈哈哈哈哈哈哈

可以先看看這個例子感受一下制作出來的幻燈片之強大：

• MPE 支持的絕大部分功能都能用于幻燈片
• 橫向/縱向切換幻燈片
• 演講者視圖和注釋（厲害厲害）
• 全局預覽
• 動畫
• 非常自由和比較方便的主題設置

這個幻燈片的源代碼在這里，可以感受一下，還是很有趣的。

功能全面，不得不服

以前上學的時候，我的一個老師曾經說過：幻燈片不需要那些花里胡哨的效果、那么多顏色、那么多動畫，重要的是將內容表達清楚。單色背景+清晰的文字，遠比圖片+動畫表達的效率要高。我當時聽了如醍醐灌頂。

后來過了幾年我發現——這就是你們賺錢不如隔壁美院輕松的原因啊！

……不說這個了，對于不是給外人看的幻燈片，用 MPE 寫還是有很多優點的：

• 拿自己寫好的文檔稍微改改分頁就能生成幻燈片
• 專注于內容，而不是表現
• 非要表現的話也完全達到了一般人用 PowerPoint 能做出來的水平。

但是客觀的說，這個幻燈片做出來也就是給自己人用的。如果要做給外人看的幻燈片，還是拜托有審美的同事幫忙好好做一個吧。

---

X 總結一下

這篇文章是想給有寫文檔需求的人安利一些好的工具。我覺得軟件，尤其是游戲的策劃都應該有一些程序基礎，在有一些程序基礎的前提下 Markdown 是非常方便的文檔工具，MPE 更可以讓文檔工作變得更有樂趣。

回顧下這篇文章的主要內容：

• 用 Markdown + Git 寫文檔真是爽
• MPE 功能很強大，請吃安利
• 用 ditta 畫簡圖輕松愉悅
• 在文檔里插入代碼，隨時驗證自己的想法
• 小型黑科技：制作動態Markdown
• 小型黑科技：使用導入文件功能進行非線性寫作
• 小型黑科技：用 Markdown 寫幻燈片

這樣 Office 三件套里有兩個可以純文本解決了。Excel...目前真不行……

XX 一些題外話

我剛開始接觸 Markdown 的時候，語法異常簡明。沒有目錄、沒有 TODO 支持、甚至沒有表格。

可以看看Markdown-語法說明來回顧下 Markdown 的香草時代。

講道理那個時候的 Markdown 不是特別實用。（HTML 的表格手寫太復雜了，所以不如不用表格。）那個時候的 Markdown 更適合寫簡短的說明或者筆記。

后來逐漸有了表格、有了 TODO 支持，我覺得特別好。再后來一些工具支持 [TOC]，我覺得很方便。有了這些東西，完全可以寫出比較完整成熟的文檔了。

再后來有了各種繪圖的插件，解放了畫圖的生產力。我對這件事懷著喜憂參半的心情。一方面這些功能真的很方便，我也經常用。另一方面，在 Markdown 里大規模插入代碼嚴重破壞了 Markdown 本身的風格。一個雖然全是文本但根本看不出渲染結果的 Markdown 一點也不讓人開心。

大概也是這個時間前后，不同環境對 Markdown 語法的支持也出現了區別。我們現在甚至不能說最初的 Markdown 語法是大家支持的最小子集。舉例來說，在 MPE 里段落間不空行也不會連成一段，沒有空行的兩行會翻譯成軟回車，有空行的翻譯成硬回車。我之前舉的兩個在線平臺支持的語法也不盡相同。我覺得這種風氣很不好。如果最后每個平臺對 Markdown 的支持都不盡相同，形成了各自的壁壘，那 Markdown 就被毀了。

我是信奉『沒有限制就沒有創造力』這一派的。所以我推薦下面這個 VSCode 插件：markdownlint，一個看名字就讓我笑出來的好東西。

目前這個插件規定了45條書寫 Markdown 的規范。大多數非常有道理，少部分非常有道理但不方便。不過我們可以在設置里手動關閉一些特定規則的語法檢查，或者設置特定規則的細節。

是的，規則025說：一級標題只能有一個，就是文檔標題。而文檔正文中的一級標題應該用二級 Markdown 標題。

裝了這個插件之后你的 Markdown 文件就會和你的代碼文件一樣到處充斥著綠色波浪線了。如果你看本文到這里能夠 get 到我的笑點的話，你可能就會猜到我看到 Markdown 里面也有綠色波浪線經常會笑出來。

遇到最嚴重的問題是，cosyvoice.flow.flow_matching - ModuleNotFoundError: No module named 'matcha.models'; 'matcha' is not a package ，那么這里的問題就出在環境變量上，文檔中設置變量的命令為：export PYTHONPATH=third_party/Matcha-TTS:$PYTHONPATH很明顯，這個指向了cosyvoice的子項目Matcha-TTS，所以為什么會遇到這個模塊缺少的原因也很明顯了。最后解決這個問題使用的命令為 $env:PYTHONPATH = "D:\test\cosyvoice\CosyVoice\third_party\Matcha-TTS;"+$env:PYTHONPATH （一次性的環境，下次需要重新設置）