Spandoc — Sublime Text 中的 Pandoc

遗憾的是，我已经将 Atom 作为我的主要文本编辑器。所以，请把这个插件视为弃用。但您可以自由地把它修改为适合自己的需求。

这是一个 Sublime Text 插件，它使用臭名昭著的开源解析器 Pandoc 将几乎任何格式的文本转换为其他格式。使用 Pandoc，您可以使用最先进的 Markdown 实现：Pandoc 的 Markdown，而使用 Spandoc，您可以在 Sublime Text 中使用它！

Spandoc 由 Brian Fisher 的插件 „pandoc“ 和 Daniel P. Shannon 的插件 Pandown 组成。 Spandoc 出现是为了结合这两个插件的优点。从 „pandoc“ 的轻量级代码库以及其命令面板功能开始，采用 Pandown 的 “项目” 配置系统，并添加了完全新的功能。代码库被彻底清理和重构。该插件正在开发中，当然 Spandoc 是由我使用的。

许可协议

MIT 许可协议，见 LICENSE.md

安装

• 安装 Pandoc
• 通过以下方式之一安装 Spandoc：
  • 包控制：运行命令：包控制：安装包，并查找 Spandoc。
  • 或 Github：从 Sublime (松散的) 软件包目录中克隆或下载 Spandoc 存储库（使用菜单 首选项->浏览软件包... 查找此文件夹）

命令

有三个命令：Spandoc 面板 和 Spandoc：配置 以及内部的 spandoc_run 命令。

Spandoc：面板

调用Sublime的命令面板（默认快捷键：ctrl+shift+p）并执行Spandoc: Palette命令。根据光标下的作用域，将展示从设置文件中定义好的变换列表。在变换列表中选择一个标签后，变换标签将被传递到内部的spandoc_run命令，并开始进行Pandoc转换。此列表可以配置，请参阅配置部分。

Spandoc: Config

此命令创建当前文件夹的设置文件（命名为spandoc.json），通过将其从用户设置文件或默认设置文件复制而来。创建后，会立即打开。如果已存在spandoc.json文件，则不会覆盖它，仅打开。

spandoc_run

spandoc_run是Spandoc的核心：它获取设置，形成pandoc命令，将pandoc命令传递给Pandoc，捕获/显示结果和失败，并将其写入文件或显示在Sublime缓冲区中（缓冲区尚未实现）。

设置结构

按加载顺序列出。

• 默认设置文件spandoc.sublime-settings，位于Sublime的Spandoc文件夹中包目录内。
• 用户设置文件spandoc.sublime-settings，位于Sublime的用户目录内。
• 文件夹设置文件spandoc.json，位于当前文件夹内（可选）。
• 用户构建系统文件Spandoc.sublime-build，位于Sublime的用户目录内（可选）。

列表底部的设置优先级高于上面的条目。文件夹设置覆盖用户设置，用户设置覆盖默认设置。

配置

建议不要更改默认设置文件，因为每次新更新都会将其覆盖。将默认设置文件复制到用户设置文件。这两个设置都可以通过应用程序菜单找到：首选项 -> 包设置 -> Spandoc。

有两种可能的顶级设置键：user和default。如果您的用户设置文件中使用default，则默认设置将被覆盖，但如果使用user，则您的设置将与默认设置合并。（此功能将被删除）

在设置中，您需要配置Pandoc可执行文件的路径。这可以通过使用pandoc-path参数完成。请参阅默认设置文件以获取默认位置。

Spandoc需要知道Pandoc的命令选项。至少需要一个输入和一个输出格式。

• 输入格式将自动从当前文档光标下的作用域中获取。

• 输出格式必须在设置文件中通过定义transformations数组来配置。使用transformations数组，您可以定义多个不同的变换。每个变换至少需要以下内容

• 变换标签/名称

• pandoc-arguments数组中含有…

  • --to参数

变换标签只是变换的名称。例如，这个名称将显示在命令面板中，并且将始终用于选择变换。--to参数以及pandoc-arguments数组中的任何其他参数必须遵循Pandoc的命名规则。

对于pandoc命令，既可以使用短版本，也可以使用长版本。例如，短版本："-o name_of_file"或长版本："--output=name_of_file"。尽管在这种情况下Sublime插件更喜欢长版本。

与原生Pandoc一样，转换结果默认写入stdout。在Spandoc和Sublime中，这意味着它将被写入缓冲区（缓冲区尚未实现，始终写入文件）。

扩展名取自相应的输出格式，该格式通过--to选项指定。然而，可以使用output_extension参数在pandoc-arguments数组之外指定文件扩展名。这在--to选项与扩展名不匹配时特别有用。以下两个示例

1. 对于PDF，必须指定：--to=latex和output_extension=pdf
2. 对于reveal.js：--to=revealjs和output_extension=html

若要将输出到文件，请使用--output选项，否则它将被写入到缓冲区（缓冲区尚未实现，它将始终写入文件，--output总是自动设置）。在将输出到文件时，文件将写回到与输入文件相同的文件夹，除非使用可选的set_path选项指定了其他目录（set_path尚未实现！）输出文件将与输入文件具有相同的名字，除非使用--output选项指定了其他名字。

请查阅Pandoc用户指南。 在pandoc-arguments内可以使用除Pandoc以外的所有可能的选项。

请注意spandoc.sublime-settings文件的格式。它应该是有效的json。当命令中包含空格时，最佳方法是使用转义引号将它们括起来，如下所示

Spandoc构建系统

使用Sublime的自动构建系统 (工具 -> 构建系统 -> 自动) 来执行内部spandoc_run命令。

没有默认的构建配置，以下是三个原因

1. 并不是每个人都在使用这个功能
2. 与用户构建配置一起使用将污染Sublime调色板（就像Pandown所做的那样）
3. 构建系统可以被轻松配置

若要使用Spandoc配置构建系统，最简单的解决方案是将以下模板复制到用户构建设置中，位置在菜单中的首选项 -> 插件设置 -> Spandoc -> 构建用户设置

{

  "selector": "text.html.markdown",
  "target": "spandoc_run",
  "transformation": "HTML",

  "variants":
    [
      { "name": "PDF", "transformation": "PDF" },
      { "name": "HTML", "transformation": "HTML (No Template)" },
    ]

}

在构建系统文件中配置transformation参数后，Sublime的自动构建系统（ctrl+b）将直接从构建系统文件将转换标签传递到内部Spandoc_run命令，并开始Pandoc转换。

快捷键

没有预定默认的键盘快捷键，但是您可以通过使用内部命令名称轻松配置它们

{
  "keys": ["ctrl+e"],
  "command": "spandoc_palette"
},

您甚至可以执行内部命令：spandoc_run，并使用键盘快捷键传递转换参数

{
  "keys": ["ctrl+e"],
  "command": "spandoc_run",
  "args": {"transformation": "HTML"}
},

贡献

贡献说明将随后给出。行为守则将随后给出。不支持Sublime 2