Sublime写支持Pandoc扩展的markdown文档

Posted 2022-12-06 苏导

简述

Markdown对于各类写作而言，非常有用，因为书写格式很简单，关键是能转成各种格式的文档，比如word pdf ppt这种，也能转成html等网页形式，这样就能适合在各种场合，写一次内容就能用于不同场景下的展示。比如这篇CSDN博客就是Marddown写的~

工具选择

之前Windows下用MarddownPad，但是貌似只支持基本Markdown语法，但是有时候整理一些比较专业的文档时，就有些不够用了，需要用Pandoc扩展语法。找了一下觉得还是直接用Sublime Text吧，起码跨平台，以后换电脑系统了可以继续用，另外MarddownPad还没找到支持Pandoc，可能付费版本有，但是不免费，觉得没必要了吧。
Pandoc看起官方介绍是，需要用命令行去进行格式转换，不过Sublime Text可以找到插件，避免这个命令行操作。

About Pandoc

写技术文档之前主要是MS Office相关办公工具来写，但是有些时候，比如需要放在网站，直接粘贴上去的情况，就不太好用了。Markdown是比较好的选择了。不过使用Markdown下来，发现功能限制还是很多的，因此要想用markdown写出更好的技术文档，就找到了pandoc了，pandoc是一个格式转换工具，同时也有更多的markdown扩展语法。

Pandoc支持的文件格式

因为一项工具和语法如果支持所有主流的格式的话，那么文档内容就可以只编辑一次，再通过工具转换为需要的格式，来在各种不同的应用场合使用。
Pandoc支持的转换前格式（书写格式）如下：
markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags, Microsoft Word docx, LibreOffice ODT, EPUB, Haddock markup

Pandoc支持的转换后格式（输出文件格式）如下：

格式类别	详细
HTML格式	XHTML, HTML5, HTML slide shows
Word processor格式	Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML
Ebooks	EPUB version 2 or 3, FictionBook2
Documentation格式	DocBook, TEI Simple, GNU TexInfo, Groff man pages, Haddock markup
Page layout格式	InDesign ICML
Outline格式	OPML
TeX格式	LaTeX, ConTeXt, LaTeX Beamer slides
PDF
轻量级markup格式	Markdown (including CommonMark), reStructuredText, AsciiDoc, MediaWiki markup, DokuWiki markup, Emacs Org-Mode, Textile
自定义格式	用lua语言自己编写

简述

在Sublime中配置好了写支持Pandoc扩展语法的markdown文档。可以看到写markdown时有语法高亮，而且写完后可以直接通过命令转换成想要的格式（目前主要在用html和pdf）。

配置过程

首先当然是要确认已经安装了package control，我早前已经安装好，其安装方法网络搜索一下，就有许多的参考。
然后安装Monokai Extended插件，MarkdownEditing插件，MarkdownTOC插件，Pandoc插件（Pandoc软件也需要首先先安装好）。如果要转换pdf，还要安装LaTex软件。

如何使用

新建.md的markdown文档后在sublime中打开，在软件右下角的文档格式选择为Markdown Extended。

这样就能够看到markdown语法高亮了。

接下来要配置Pandoc插件，如下是几分配置文件参考示例：

  // There are 2 possible top level settings keys, "user" and "default". If you
  // use "default" in your user settings file, the default settings will be
  // overwritten, but if you use "user" your settings will be merged into the
  // default settings.
  "default": 

    // path to the pandoc binary. Default locations per platform:
    // -  mac
    //    "pandoc-path": "/usr/local/bin/pandoc",
    // -  windows
    //    "pandoc-path": "C:/Users/[username]/AppData/Local/Pandoc/pandoc.exe",
    "pandoc-path": null,

    // transformations
    "transformations": 

      // label of transformation, to appear in sublime quick panel. This should
      // be a name related to the format of the output.
      "Markdown (Pandoc)": 
        // Opens output in new buffer (instead of replacing input in same buffer)
        "new-buffer": 1,
        // maps sublime scope to input format. If the input matches against the
        // given scope, this transformation becomes available, and the input
        // format is used as the pandoc --from option.
        // @see http://docs.sublimetext.info/en/latest/extensibility/syntaxdefs.html#scopes
        // @see score_selector() http://www.sublimetext.com/docs/3/api_reference.html
        // @see http://johnmacfarlane.net/pandoc/README.html#options
        "scope": 
          "text.html": "html"
        ,
        // sublime syntax file of output format, will set output to this syntax
        "syntax_file": "Packages/Markdown/Markdown.tmLanguage",
        // additional arguments passed to pandoc
        // -  --from is automatically set, see "scope" above
        // -  --to=FORMAT or one of its aliases is required
        // @see http://johnmacfarlane.net/pandoc/README.html#options
        "pandoc-arguments": [
          "--to=markdown",
          "--wrap=none",
          "--atx-headers"
        ]
      ,

      "HTML 5": 
        "new-buffer": 1,
        "scope": 
          "text.html.markdown": "markdown"
        ,
        "syntax_file": "Packages/HTML/HTML.tmLanguage",
        "pandoc-arguments": [
          "--to=html5",
          "--no-highlight"
        ]
      ,

      // note these are examples of output formats that should not be opened in a
      // sublime text buffer. See "pandoc-format-file" below

      // @see http://johnmacfarlane.net/pandoc/README.html#creating-a-pdf
      "PDF": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown"
        ,
        // use to place the output in the same directory as the curent file
        // if -o or --output are set in "pandoc-arguments" this is ignored
        // "out-local": true,
        "pandoc-arguments": [
          "-t", "pdf"
          // use --latex-engine=engine where engine is
          // pdflatex|lualatex|xelatex. This may need to be specified with a
          // full path, e.g. on a mac with BasicTeX
          // "--latex-engine=/usr/texbin/pdflatex"
          // or on Windows with MiKTeX
          // "--latex-engine=C:/Program Files (x86)/MiKTeX 2.9/miktex/bin/pdflatex.exe"
          // if -o or --output missing, will write to a temporary file
          // "--output=~/Downloads/output.pdf"
        ]
      ,

      "Microsoft Word": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown"
        ,
        "pandoc-arguments": [
          "-t", "docx"
          // if -o or --output missing, will write to a temporary file
          // "--output=~/Downloads/output.pdf"
        ]
      ,

      "PDF TOC (Narrow margins)": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown",
          ,
        "pandoc-arguments": [
          "-V", "geometry:margin=1.25in",
          "-s", "--toc", "--number-sections", "--parse-raw",
          "-t", "pdf",
        ],
      ,

      "PDF TOC": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown",
          ,
        "pandoc-arguments": [
          "-s", "--toc", "--number-sections", "--parse-raw",
          "-t", "pdf",
         ],
      ,

      "HTML TOC": 
        "new-buffer": 1,
        "scope": 
          "text.html.markdown": "markdown"
        ,
        "syntax_file": "Packages/HTML/HTML.tmLanguage",
        "pandoc-arguments": [
          "--to=html5",
          "--no-highlight",
          "-s", "--toc"
        ]
      ,

      "Beamer Slides (PDF)": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown",
        ,
        // Use the "out-ext" parameter to define a custom output file extension. Commonly used for pdf.
        "out-ext": "pdf",
        "pandoc-arguments": [
          "-t", "beamer",
          "--latex-engine=C:/Program Files (x86)/MiKTeX 2.9/miktex/bin/pdflatex.exe"
        ]
      ,

      "Beamer Slides (LaTeX)": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown",
        ,
        "pandoc-arguments": [
          "-t", "beamer",
        ]
      ,

      "s5 Slides": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown",
        ,
        "pandoc-arguments": [
          "-t", "slidy", "-s", "--self-contained",
        ]
      ,
    ,
    // these should not need to be customized

    // output formats that are written to file, using -o parameter. These we do
    // not output to a sublime text buffer.
    "pandoc-format-file": ["docx", "epub", "pdf", "odt", "beamer"]
  

  "default": 
    "pandoc-path": "C:/Program Files (x86)/Pandoc",

    "transformations": 

      "HTML": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown"
        ,
        "pandoc-arguments": [
          "-o"
        ]
      ,

      "PDF": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown"
        ,
        "pandoc-arguments": [
          "-t", "pdf", **"--latex-engine=/usr/texbin/pdflatex"**,
          **"--filter=/usr/local/bin/pandoc-citeproc"**,
          **"--bibliography=/Users/frank/Documents/Mendeley/reference.bib"**
        ]
      ,

      "Microsoft Word": 
        "scope": 
          "text.html": "html",
          "text.html.markdown": "markdown"
        ,
        "pandoc-arguments": [
          "-t", "docx",
          **"--filter=/usr/local/bin/pandoc-citeproc"**,
          **"--bibliography=/Users/frank/Documents/Mendeley/reference.bib"**
        ]
      

    ,

    "pandoc-format-file": ["html", "docx", "epub", "pdf", "odt"]
  

  // Sets the path to the pandoc binary.
  "pandoc-path": null,

  // Opens output in new buffer (instead of replacing input in same)
  "new-buffer": 1,

  // configure Pandoc executable
  // see http://johnmacfarlane.net/pandoc/README.html#options

  // enabled Pandoc formats
  // key: label, value: Pandoc format key (-f or -t values)
  "formats": 
    "AsciiDoc": "asciidoc",
    "LaTeX beamer slide show": "beamer",
    "ConTeXt": "context",
    "DocBook XML": "docbook",
    "Word docx": "docx",
    "HTML5 + javascript slide show": "dzslides",
    "EPUB v2": "epub",
    "EPUB v3": "epub3",
    "FictionBook2 e-book": "fb2",
    "Haddock": "haddock",
    "XHTML 1": "html",
    "HTML 5": "html5",
    "JSON version of native AST": "json",
    "LaTeX": "latex",
    "Groff man": "man",
    "Markdown": "markdown",
    "Markdown (Github extended)": "markdown_github",
    "Markdown (php Markdown Extra extended)": "markdown_phpextra",
    "Markdown (Strict)": "markdown_strict",
    "MediaWiki markup": "mediawiki",
    "Native Haskell": "native",
    "OpenOffice text document": "odt",
    "OpenDocument XML": "opendocument",
    "OPML": "opml",
    "Emacs Org-Mode": "org",
    "PDF": "pdf",
    "reveal.js HTML5 + javascript slide show": "revealjs",
    "Rich Text Format": "rtf",
    "plain text": "plain",
    "reStructuredText": "rst",
    "S5 HTML and javascript slide show": "s5",
    "Slideous HTML and javascript slide show": "slideous",
    "Slidy HTML and javascript slide show": "slidy",
    "GNU Texinfo": "texinfo",
    "Textile": "textile"
  ,

  // format configuration
  // key: format_[key] where [key] is the Pandoc format key (-f or -t values)
  // - scope: input sublime scope. Missing implies pandoc can not accept the
  //   format as input (@todo fix this, allow multiple input formats per scope)
  // - syntax_file: sublime syntax file of output format, will set output to
  //   this syntax
  // - from: list of pandoc options to add when used as input
  // - to: list of pandoc options to add when used as output
  "format_asciidoc": ,
  "format_beamer": 
    "syntax_file": "Packages/LaTeX/LaTeX Beamer.tmLanguage"
  ,
  "format_context": 
    "syntax_file": "Packages/LaTeX/LaTeX.tmLanguage"
  ,
  "format_docbook": 
    // "scope": "text.xml",
    "syntax_file": "Packages/XML/XML.tmLanguage"
  ,
  "format_docx": ,
  "format_dzslides": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"
  ,
  "format_epub": 
    "syntax_file": "Packages/XML/XML.tmLanguage"
  ,
  "format_epub3": 
    "syntax_file": "Packages/XML/XML.tmLanguage"
  ,
  "format_fb2": ,
  "format_haddock": ,
  "format_html": 
    "scope": "text.html",
    "syntax_file": "Packages/HTML/HTML.tmLanguage"  ,
  "format_html5": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"  ,
  "format_json": 
    "scope": "source.json",
    "syntax_file": "Packages/JavaScript/JSON.tmLanguage"
  ,
  "format_latex": 
    "scope": "text.tex.latex",
    "syntax_file": "Packages/LaTeX/LaTeX.tmLanguage"
  ,
  "format_man": ,
  // pandoc by default uses an enhanced version of markdown, see
  // http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
  // to disable:
  //    -   pandoc <1.10: add "--strict" to "to" or "from"
  //    -   pandoc >=1.10: use markdown_strict output format
  "format_markdown": 
    "scope": "text.html.markdown",
    "syntax_file": "Packages/Markdown/Markdown.tmLanguage",
    "to": ["--no-wrap", "--atx-headers"],
    "from": ["--no-highlight"]
  ,
  "format_markdown_github": 
    // "scope": "text.html.markdown",
    "syntax_file": "Packages/Markdown/Markdown.tmLanguage"
  ,
  "format_markdown_phpextra": 
    // "scope": "text.html.markdown",
    "syntax_file": "Packages/Markdown/Markdown.tmLanguage"
  ,
  "format_markdown_strict": 
    // "scope": "text.html.markdown",
    "syntax_file": "Packages/Markdown/Markdown.tmLanguage"
  ,
  "format_mediawiki": 
    "scope": "text.html.mediawiki",
    "syntax_file": "Packages/Mediawiker/Mediawiki.tmLanguage"
  ,
  "format_native": 
    "scope": "source.haskell",
    "syntax_file": "Packages/Haskell/Haskell.tmLanguage"
  ,
  "format_odt": ,
  "format_opendocument": 
    "syntax_file": "Packages/XML/XML.tmLanguage"
  ,
  "format_pdf": 
    // use --latex-engine=engine where engine is one of pdflatex|lualatex|xelatex
    // This may need to be specified with a full path (e.g. on a mac with
    // BasicTeX "/usr/texbin/pdflatex").
    "to": ["--latex-engine=/usr/texbin/pdflatex"]
  ,
  "format_rtf": ,
  "format_opml": 
    // "scope": "text.xml",
    "syntax_file": "Packages/XML/XML.tmLanguage"
  ,
  "format_org": ,
  "format_plain": 
    "syntax_file": "Packages/Text/Plain text.tmLanguage"
  ,
  "format_revealjs": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"
  ,
  "format_rst": 
    "scope": "text.restructuredtext",
    "syntax_file": "Packages/RestructuredText/reStructuredText.tmLanguage"
  ,
  "format_s5": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"
  ,
  "format_slideous": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"
  ,
  "format_slidy": 
    "syntax_file": "Packages/HTML/HTML.tmLanguage"
  ,
  "format_texinfo": 
    "syntax_file": "Packages/LaTeX/LaTeX Beamer.tmLanguage"
  ,
  "format_textile": 
    "scope": "text.html.textile",
    "syntax_file": "Packages/Textile/Textile.tmLanguage"
  

我这里选择了第一种配置，在写完了markdown文档后，用Ctrl + Shift + P调出package control，然后输入Pandoc，选择Pandoc插件，会弹出如下的界面：

就可以选择要转换的格式，我这里选择了带目录的html格式–HTML TOC，然后会生成对应的html文档并自动在sublime中打开，转换其他格式的文档也是类似流程。

参考文章

这篇很不错