MarkdownPreview官方APi 和 如何使其支持公式

話不多說,先上官方的網站 https://facelessuser.github.io/MarkdownPreview/ 和該插件在GitHub 上的連接 https://github.com/facelessuser/MarkdownPreview/ 。該插件可以讓我們在 sublime 中非常棒的書寫體驗,而且不需要你每次都對 md 文檔進行實時預覽。當然你也可以配合其他同類的軟件進行實時的預覽,但是在我對 Markdown 語法比較熟悉之後,我並不喜歡這種實時預覽的方式,主要原因在於實時預覽比較消耗性能,並沒有直接碼MD快速。更重要的是,很多時候自帶的一些Markdown編輯器總是無法滿足我自己的需求。比如,轉換成公衆號的排版,快速的插入本地和網絡圖片、latex語法的支持。

如果說大家並不喜歡折騰的Markdown語法愛好者,我覺得 Typora 算是我用過的 MD 編輯器中最好用且功能最全,最重要的是還免費。 附上Typora 的下載鏈接讓各位看官自行下載。

喜歡 MarkdownPreview 的主要原因只有一個,讓寫MD文檔和寫代碼一樣簡單

在這裏我主要翻譯一下Markdown Preview 官網上的英文使用用法,讓自己對這個插件的使用更加的深入。

Usage

安裝參考: https://packagecontrol.io/packages/MarkdownPreview 中的介紹

PS: 2018/8/14 最新的 MarkdownPreview 中的版本測試過,是沒有問題的。

在有網的情況下:

  1. 打開命令面板,快捷鍵是 (ctrl+shift+p)
  2. 在面板中輸入如下命令,Package Control: Install Package
  3. 選中後再次輸入 MarkdownPreview 就可以查詢到 MarkdownPreview 插件
  4. 按下 enter 鍵就可以在線進行安裝。

安裝插件

離線安裝,直接可以自行百度

提示

在安裝好插件後,在 sublime 中的找到 Preferences->Package Settings->MarkdownPreview.中找到設置。其中 User 表示用戶設置,default 表示 MarkdownPreview 中默認設置。

安裝好之後MarkDownPreview設置

預覽 To preview

當你像我這樣碼號MD之後,使用 Cmd+Shift+P 就可以展示如下的命令。按照需求選擇其中一個就可以解析你的MD文檔。各個命令解釋如下

  • Markdown Preview: Preview in Browser
  • Markdown Preview: Export HTML in Sublime Text
  • Markdown Preview: Copy to Clipboard
  • Markdown Preview: Open Markdown Cheat sheet

各個操作的效果,各位看官可以自己動手操作試試,沒有別的明確需求就選第一個 Markdown Preview: Preview in Browser,將會在默認的瀏覽器中打開你的md渲染後的html文件。

具體的操作動圖

上面的這些操作都已經默認的綁定了快捷鍵,你可以在也在 Preferences --> Keybindings 中設置快捷鍵。添加如下命令,綁定 alt+m 快捷鍵。

{ "keys": ["alt+m"], "command": "markdown_preview", "args": {"target": "browser", "parser":"markdown"} },

自定義模板 Custom Templates

默認的情況下,MarkdownPreview 使用的是一個簡單模板,但你可以通過 setting 中的 html_template 選項來指定你自己的模板絕對路徑。可以參考安裝目錄下的 Data/Installed Packages/MarkdownPreview.sublime-package中的MarkdownPreview/samples/customized-template-sample.html"文件。

預覽路徑 Preview Path Conversion

通常的我們的路徑存在『相對路徑』和『絕對路徑』。在設置中兩個地方需要指定,對於圖片我們還可以指定爲 base64 格式,該格式會將本地的文件嵌入到html文件中,對於不是很大的文件這種方式我個人是最喜歡的。這樣我將html直接複製到別的地方就不會出現文件找不到情況。

    "image_path_conversion": "base64",
    "file_path_conversions": "absolute",

預覽臨時文件位置 Preview Temp Location

通常就是系統將渲染後的 html 文件存放的臨時目錄,根據渲染後的網頁,在瀏覽器中打開的網址就可以判斷出,默認就是系統的臨時目錄。當然你也可以更改該路徑來符合你的需求。

    "path_tempfile": "/tmp/my_notes",

添加其它的 Markdown 解析器 Enabling Other External Markdown Parsers

在 MarkdownPreview 中默認的設置 markdown_binary_map 選項,每一個選項中都包含了key-value 的結構。key 就是新的解析器名稱,value 是一個數組,其中第一項是表示該解釋器的位置,後面依次跟着
該解析器期望給出的參數。 默認的三個解析器爲 Markdown, GitHub, gitlab。 這個 markdown 是一個離線的解析器,默認我就習慣使用這個。 其它的兩個,都是調用了網絡上對應網址的APi來進行解析的。

    "markdown_binary_map": {
        "multimarkdown": ["/usr/local/bin/multimarkdown", "--some-option", "some-value"]
    },

該解析器可以在 enabled_parsers 屬性中添加,這樣在就可以在解析時指定

    "enabled_parsers": ["markdown", "github", "gitlab", "multimarkdown"],

Configuring Python Markdown Extensions

Python Markdown 擴展很多Markdown 插件,也可以使用許多第三方擴展。 markdown_extensions 選項是他們導入路徑的一種形式。

支持公式

支持 latex 公式,主要在官網的擴展中提到。默認情況設置下,是不支持 latex 渲染的。

支持 MathJax

首先需要申明的是,GitHub 和 GitLab 解析器是不支持 MathJax 的語法的。所以,如果你開啓了MathJax 功能,但是卻調用了 GitHub 或者 GitLab API 來解析,有可能會導致轉換該 MathJax 語法時出現問題。

開啓方式就是在用戶設置文檔中增加如下內容。官網上面設置的語法存在一個逗號的錯位問題。你需要將下面的配置,加入到
markdown_extensions 屬性配置中。

    "markdown_extensions": [
        // MathJax Support(支持 Latex)
        // Danger!!! GitHub and GitLab is not supported with MathJax. 
        // You will have to come up with a MathJax config that works for
        // it and escape problematic syntax that GitHub may try to convert.
        {
            "pymdownx.arithmatex": {
                "generic": true,
            }
        },
    ]

只加入上面的語句,只是表示你開啓了Math公式解析的支持,還需要指定 MathJax 或者 LaTex 渲染庫的位置(js語法不清楚,也不知道這樣解釋是否正確)。 在同樣的配置文件中,指定 js 屬性。

    "js": {
        "markdown": [
            "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js",
            "res://MarkdownPreview/js/math_config.js"
        ],
        "github": ["default"],
        "gitlab": ["default"]
    }

你也可以自定義指定 MathJax 庫中的位置。

KaTeX 的支持

GitLab 默認是已經支持了 KaTex. 我們只需要在 Js 和 CSS 屬性中添加就可以啦。同樣的GitHub是不支持的。

同樣,按照上面的思路,將將 Js 替換,在這裏還增加了 CSS 屬性。

    "js": {
        "markdown": [
            "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js",
            "res://MarkdownPreview/js/katex_config.js"
        ]
    },
    "css": {
        "markdown": [
            "default",                                                            // <- The default Markdown CSS.
            "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css", // <- KaTeX CSS
            "res://MarkdownPreview/css/katex_eqnum.css"                           // <- Optional equation numbering CSS
        ]
    },

UML 支持

同樣的指出了 GitHub 不支持 UML. 我暫時沒有用到該功能,而且感覺用起來也很麻煩,還是老實的截圖好啦。
官網說明鏈接

參考資料

  1. PyMarkdown 的解析器官網介紹
  2. 關於在MarkdownPreview 中插入公式支持的官網介紹
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章