近乎完美的Markdown写作体验 - SublimeText3 + OmniMarkupPreviewer

赏弘

2023-12-01

近乎完美的Markdown写作体验 - SublimeText3 + OmniMarkupPreviewer

这篇blog的初衷是因为最近要开始写论文，打算用LaTex，在安装过程中发现了markdown_preview，回来想想自己一直用的Cmd Markdown，但如果想转pdf得要会员注册，貌似字号跟行距也是设计好的，总感觉不那么对味．
在装完markdown_preview以后，发现mp的以下缺点:

不支持本地LaTex的数学公式
不支持浏览器的实时渲染

在解决1的过程中的时候，找到了OmniMarkupPreviewer，他提供了LaTex的数学公式渲染的支持，用浏览器打开以后发现居然还支持支持浏览器的实时渲染．果断弃了mp.

什么是 Markdown

Markdown 是一种轻量级标记语言，创始人为约翰·格鲁伯（John Gruber）。它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML(或者HTML)文档”。 —— 来自维基百科

Markdown 创立的宗旨是实现「易读易写」。其语法简洁直观，你可以使用任何喜爱的文本编辑器来阅读和写作，更专注于书写的文字内容而不是排版样式。编辑完毕可轻松地导出成 HTML、PDF 等其它格式。

语法学习参考 : Markdown 语法说明(简体中文版)

Sublime Text 3 以及 OmniMarkupPreviewer

Sublime Text 是一套跨平台的文字編輯器，支持基於Python的外掛程式。Sublime Text 是專有軟體，可透過套件（Package）擴充本身的功能。大多數的套件使用自由軟體授權釋出，並由社群建置維護。 —— 来自维基百科

Sublime Text 作为近些年迅速崛起的后起之秀，凭借其精美的 UI 交互、完备的特色功能俘虏了一大批忠实用户。其风靡之势刺激了一些新老文本编辑器的重新思考和开发，开源实现 Lime Text Editor 无需多说，Github 主导的 Atom 以及号称下一代 Vim 编辑器的 neovim 都明确受到 Sublime Text 的影响。
而 OmniMarkupPreviewer 作为 Sublime Text 的一款强大插件，支持将标记语言渲染为 HTML 并在浏览器上实时预览，同时支持导出 HTML 源码文件。

OmniMarkupPreviewer 设置详解

安装和使用

你可以在 Sublime Text 内通过 Package Control 输入 Install Package 来安装 OmniMarkupPreviewer, 也可以从其 Github主页下载压缩包，解压到 Sublime Text 的 Packages 目录即可完成安装。

新建文件(ctrl + n),选择语法格式为：markdwon
输入文本Hello World!!!
Preview Current Markup in Browser。(ctrl + alt + p，输入omni进行选择)
此时，你会发现，文档中的任何修改都会在浏览器中体现出来

详细设置

OmniMarkupPreviewer 默认配置基本够用，但详细设置后才能将其特色功能充分发挥。
通过点击菜单栏 Preferences - Packages Settings - OmniMarkdownPreviwer - Setting-Default 我直接在默认配置文件上改了，你可以自己复制一份到Setting-user，然后做出修改．

/* OmniMarkupPreviewer default setting, DO NOT MODIFY */
{
    "server_host": "127.0.0.1",
    "server_port": 51004,
    "refresh_on_modified": true,
    // delay after modified, in milliseconds
    "refresh_on_modified_delay": 500,
    "refresh_on_saved": true,

    // User defined command for launching preview in web browser
    // For example:
    //   Launching preview using Google Chrome in OS X:
    //      ["open", "-a", "Google Chrome", "{url}"]
    "browser_command": [],

    // User public static files should be placed into
    //   ${packages}/User/OmniMarkupPreviewer/public/
    // User templates should be placed into:
    //   ${packages}/User/OmniMarkupPreviewer/templates/
    // Requires browser reload
    // Built-in templates: github, github-v1
    "html_template_name": "github",

    // Polling interval for content changes in web browsers, in milliseconds
    // Requires browser reload
    "ajax_polling_interval": 500,

    // list of renderers to be ignored, case sensitive.
    // Valid renderers are: "CreoleRenderer", "MarkdownRenderer", "PodRenderer",
    //     "RDocRenderer", "RstRenderer", "TextitleRenderer"
    // for example, to disable Textile and Pod renderer:
    //   "ignored_renderers": ["TextitleRenderer", "PodRenderer"]
    "ignored_renderers": ["LiterateHaskellRenderer"],

    // Enable MathJax (http://www.mathjax.org/)
    // MathJax javascript libraries will downloaded automatically, it may take some while.
    // When MathJax is properly installed into OmniMarkupPreviewer/public/mathjax, you
    //   have to reload your browser to get mathjax work.
    // KNOWN ISSUES:
    //   * It may be slow base on your computer/browser performance, so you may want to
    //     tune the following options:
    //         "ajax_polling_interval", "refresh_on_modified" and "refresh_on_modified_delay"
    "mathjax_enabled": true,

    // Custom options for exporting
    "export_options" : {
        // follow "html_template_name" rules
        // Built-in templates: github-export, github-v1-export
        "template_name": "github-export",
        // ".":  export to the same folder as markup file.
        // null: export to system temp folder.
        // NOTE: folder shall exist, or it will fallback to system temp folder.
        "target_folder": ".",
        // format string for filename timestamp
        "timestamp_format" : "_%y%m%d%H%M%S",
        "copy_to_clipboard": false,
        // Open with default browser or whatever customized in "browser_command".
        "open_after_exporting": false
    },

    // MarkdownRenderer options
    "renderer_options-MarkdownRenderer": {
        // Valid extensions:
        // - OFFICIAL (Python Markdown) -
        //   "extra": Combines ["abbr", "attr_list", "def_list", "fenced_code", "footnotes", "tables", "smart_strong"]
        //            For PHP Markdown Extra(http://michelf.ca/projects/php-markdown/extra/)
        //   "abbr": http://packages.python.org/Markdown/extensions/abbreviations.html
        //   "attr_list": http://packages.python.org/Markdown/extensions/attr_list.html
        //   "def_list": http://packages.python.org/Markdown/extensions/definition_lists.html
        //   "fenced_code": http://packages.python.org/Markdown/extensions/fenced_code_blocks.html
        //   "footnotes": http://packages.python.org/Markdown/extensions/footnotes.html
        //   "tables": http://packages.python.org/Markdown/extensions/tables.html
        //   "smart_strong": http://packages.python.org/Markdown/extensions/smart_strong.html
        //   "codehilite": http://packages.python.org/Markdown/extensions/code_hilite.html
        //   "meta": http://packages.python.org/Markdown/extensions/meta_data.html
        //   "toc": http://packages.python.org/Markdown/extensions/toc.html
        //   "nl2br": http://packages.python.org/Markdown/extensions/nl2br.html
        // - 3RD PARTY -
        //   "strikeout": Strikeout extension syntax - `This ~~is deleted text.~~`
        //   "subscript": Subscript extension syntax - `This is water: H~2~O`
        //   "superscript": Superscript extension syntax 0 `2^10^ = 1024`
        //   "smarty" or "smartypants": Python-Markdown extension using smartypants to emit
        //                   typographically nicer ("curly") quotes, proper
        //                   ("em" and "en") dashes, etc.
        //                   See: http://daringfireball.net/projects/smartypants/
        //                   And: https://github.com/waylan/Python-Markdown/blob/master/docs/extensions/smarty.txt
        "extensions": ["tables", "strikeout", "fenced_code", "codehilite", "attr_list", "subscript", "superscript"]
    }
}

结合配置文件注释，来一起看下让 OmniMarkupPreviewer 更好用的诸多选项:

"server_host": "127.0.0.1",

开启预览服务的 IP 地址, 默认为 localhost.

此处建议设置为本机固定 IP. 其好处在于：从局域网内的任意一台设备均可访问，可多设备同时在线，实现一处编辑、多端预览的效果。

你完全可以在 Mac 上编辑 Markdown 文档，而把 iPad 当作外接显示器来实时预览。

"browser_command": []

预览默认为跟随系统默认浏览器，[“open”, “-a”, “Google Chrome”, “{url}”]亦可利用这样的格式进行指定．

"html_template_name": "github",

预览使用的模板名称，默认为 Github.

所谓模板其实就是非常简单的 CSS + HTML 文件，你可以修改背景、行宽、字体、边距 …… 等等样式相关的所有东西，甚至引入一些花哨的动画效果。

你可以在内置模板 Github 的基础上进行自定义，其路径为 ${packages}/OmniMarkupPreviewer/public/github.css, ${packages}/OmniMarkupPreviewer/templates/github.tpl. 修改完毕后依据注释提示分别放到相关路径即可。

 "ignored_renderers": ["LiterateHaskellRenderer"],

忽略/关闭的标记语言渲染器。
支持的标记类语言:
* Markdown
* reStructuredText
* WikiCreole
* Textile
* Pod (Requires Perl >= 5.10)
* RDoc (Requires ruby in your PATH)
* Org Mode (Requires ruby, and gem org-ruby should be installed)
* MediaWiki (Requires ruby, as well as gem wikicloth)
* AsciiDoc (Requires ruby, as well as gem asciidoctor)
* Literate Haskell

"mathjax_enabled": false,

设置。公式的渲染使用了MathJax库，所以需要在OmniMarkupPreviewer的设置中，将”mathjax_enabled”设置为“true”。之后MathJax会在后端自动下载。
可能是网速的原因，MathJax库下载很慢，所以可以选择手动安装。

下载MathJax：https://github.com/downloads/timonwong/OmniMarkupPreviewer/mathjax.zip
然后解压到下面的目录里：
${Packages} \OmniMarkupPreviewer\public
之后在目录${Packages} \OmniMarkupPreviewer中创建一个空文件MATHJAX.DOWNLOADED
这样子MathJax就安装成功了。

"extensions": ["tables", "strikeout", "fenced_code", "codehilite", "attr_list"]

Markdown 渲染扩展选项。

对比某些功能缺失的 Markdown 编辑器就知道 OmniMarkupPreviewer 的强大之处，简单说下：

attr_list: 定义 HTML 标签属性
语法：{#someid .someclass somekey='some value' }
基本用途是实现篇幅较长的文档内的随意跳转。
开启 attr_list 支持后，实现语法非常简洁：

{#jumpid}
### 想要跳转到这里？ 

从页面的任何地方跳转到 [click](#jumpid "跳转到'想要跳转到这里？'")

footnotes: 文档脚注
本文就使用了一些脚注来标记参考文档的网址。
语法：

[Footnotes][1] have a label and content.
[1]: This is a footnote content.

toc: 文档目录
文章开头自动生成文档目录，并附带跳转链接。对了解长篇文章结构和快速跳转有较大帮助。
语法： Markdown 文档相应位置输入 [TOC] 即可
codehilite: 代码块语法高亮支持
需要 Pygments 库，支持300种语言及其它文本格式的语法高亮，并可以方便地自定义代码高亮样式。
如果之前没安装过 Pygments 的话，打开终端输入 pip install pygments 即可。
其它：

strikeout 删除线： This ~~is deleted text.~~

superscript 上标： 2^10^ = 1024

subscript 下标： This is water: H~2~O

特别需要注意：

在测试过程中出现以下情况：

Error: 404 Not Found

Sorry, the requested URL 'http://127.0.0.1:51004/view/28' caused an error:

'buffer_id(28) is not valid (closed or unsupported file format)'

**NOTE:** If you run multiple instances of Sublime Text, you may want to adjust
the `server_port` option in order to get this plugin work again.

我们需要对配置文件做出修改（sublime版本：3126beta）

**Quick Fix 1:** 移除扩展

Sublime Text > Preferences > Package Settings > OmniMarkupPreviewer > Settings - User
粘贴下列的扩展去代替原来的扩展（我用了方法1）

{
    "renderer_options-MarkdownRenderer": {
        "extensions": ["tables", "fenced_code", "codehilite"]
    }
}


Quick Fix 2: Fix the Strikethrough Extension (if you need it)

Find the python-markdown sublime package.（反正我是没成功）

On the Mac: subl "/Users/<username>/Library/Application Support/Sublime Text 3/Packages/OmniMarkupPreviewer/OmniMarkupLib/Renderers/libs/mdx_strikeout.py"

Replace the makeExtension() method with the following:

def makeExtension(*args, **kwargs):
    return StrikeoutExtension(*args, **kwargs)
Save, quit and reload Sublime Text.

参考自：http://macplay.github.io/cool-software/perfect-markdown-writing-experience-from-st3/#fn:toc
https://github.com/timonwong/OmniMarkupPreviewer/issues/85

近乎完美的Markdown写作体验 - SublimeText3 + OmniMarkupPreviewer

近乎完美的Markdown写作体验 - SublimeText3 + OmniMarkupPreviewer

什么是 Markdown

Sublime Text 3 以及 OmniMarkupPreviewer

OmniMarkupPreviewer 设置详解

安装和使用

详细设置

相关阅读

相关文章

相关问答

相关文档