pandoc风格

此脚本允许您为 pandoc 定义样式。在您可以定义的样式中，应该为不同的格式调用哪些参数 pandoc。此外，它允许在转换之前和之后运行脚本，并为这些脚本和过滤器提供强大的功能。

• pandoc风格
  • 安装
    • 要求
    • 安装
    • 设置
  • 用法
  • 定义样式
    • 基本用法
    • 遗产
  • 样式包
  • 高级功能
    • 寻址配置文件夹中的文件
    • 逐字变量
    • 预检
    • 处理 Sass
    • 添加到模板
    • 在模板中替换
    • 在输出中替换
    • 飞行后
    • 筛选
    • 高级示例
  • 命令行工具
  • 创建样式包

安装

要求

要使用此脚本，您需要以下内容：

1. Python 3.6 或更高版本：您可以在此处获取 python。

2. Pandoc 2.11 或更高版本：您可以在此处下载 pandoc。

安装

现在您需要自行安装此脚本。打开控制台并输入：

pip3 install pandoc_styles
pandoc-styles --init

设置

根据您的系统，您可能需要配置一些设置才能正常工作。初始化后，此脚本在您的用户文件夹中创建了目录“pandoc_styles”。在里面你可以找到 config.yaml 文件。在其中设置系统所需的选项。

用法

“pandoc_styles”文件夹可用作存储样式、脚本、过滤器等的中心点。一些子文件夹是预先创建的供您使用。

“styles.yaml”文件包含所有样式。您可以在此处定义样式，脚本会在此处查找文件元数据块中指定的样式。

要使用您的样式，您的源文件需要有一个元数据块。此脚本可识别块中的这些命令：

• 样式：用于文件的样式列表
• style-defintion：除了在“styles.yaml”文件中定义样式外，你也可以在这里定义样式。此处给出的样式设置优先于“styles.yaml”中给出的设置
• 格式：源文件应转换为的格式列表。如果没有给出，则构建 html 和 pdf 文件。
• 目的地：创建输出的目录。
• output-name：输出文件的所需名称，不带扩展名。如果没有给出，则使用文件名。
• 样式中存在的字段。它们覆盖样式中给出的默认值。

如果将文件夹中的所有文件转换为一个文档，则可以使用以下附加命令：

• 文件列表：准确指定应转换文件夹中的哪些文件。
• exclude-files：将列出的文件从beeing 转换中排除。

然后要转换您的文件，请打开控制台并输入：

pandoc-styles "your_file"

或者，如果要将文件夹中的所有文件转换为一个文档：pandoc-styles -f

命令行脚本有许多可用于宏、批处理文件等的可选参数。输入

pandoc-styles -h

查看所有选项。

定义样式

基本用法

样式是用 yaml 编写的，就像 pandoc 元数据块一样。样式定义如下：

Name:
  format:
      pandoc-option: value
      pandoc-variable: value

“名称”是样式的寻址方式。元数据块中直接定义的样式没有名称。“格式”指定应调用以下命令的格式。有一个特殊的值：“全部”。“全部”下的所有内容以任何格式使用。格式的示例是 html、pdf、latex、epub 等。

在格式下，您只需输入 pandoc 选项和变量。如果参数是标志，请使用“true”。给定值“false”的参数将被忽略。

一个基本的例子

这是源文件中的示例元数据块：

---
title:  Example
author: John Doe
formats:
    - html
    - pdf
style-definition:
    all:
        toc: true
        toc-depth: 3
        highlight-style: tango
        language: en
    html:
        standalone: true
    pdf:
        pdf-engine: xelatex
---

遗产

样式可以有一个名为“继承”的字段。这是它继承的其他样式的列表。列表中较低的样式会更新较高的样式。制定了以下规则：

• 单个值被替换
• 如果一个值是另一个字典，则将新值附加到它，如果一个值存在，则在其上再次使用这些规则
• 如果一个值是一个列表，则将新值附加到它上面。

样式包

可以捆绑特定样式所需的所有文件并将其作为样式包共享。您可以通过将样式包的内容提取到 config 文件夹内的样式文件夹中或通过 pandoc_styles_tools 命令行界面和 optionimport命令来安装样式包。

要使用样式包，请在元数据中包含字段“样式包”。它看起来像这样：

stylepacks:
  - stylepack_1_name:
    - style_1
    - style2
  - stylepack_2_name

如果您没有从样式包中指定样式，它将使用其默认样式。

例子

pandoc_styles: novel是一个样式包，可以从你的源文件中创建小说。使用此样式包的文档可以在 github 页面上找到，并且在安装包的样式文件夹中。您可以使用以下命令安装它：

pandoc-styles-tools import novel -u https://github.com/dickloraine/pandoc_styles_novel/releases/latest/download/novel.zip

高级功能

寻址配置文件夹中的文件

如果在路径前加上“~/”，则可以指向配置目录中的文件。该脚本首先搜索给定的路径，然后在适当命名的子文件夹中查找，最后在“misc”子文件夹中查找。例如：

filter:
  - ~/test-filter.py

将在配置目录的子文件夹“filter”中找到文件“test-filter.py”。

逐字变量

如果您需要不应该以输出格式呈现的模板变量（例如文件路径），您可以在“逐字变量”字段下添加这些变量：

verbatim-variables:
  my-path: "my/path"

一些变量是预定义的，并且总是可以在模板中使用：

• config-dir：配置目录的路径
• stylepackName-dir：给定样式包的目录路径
• temp-dir：当前使用的临时目录的路径

预检

您可以在转换发生之前运行其他命令行应用程序和脚本。只需在样式定义的预检字段中输入命令行命令即可。您可以将文件列表传递给它<files>。将值显式标记为字符串，以避免特殊字符的任何麻烦。例如：

Test-style:
  html:
    preflight:
      - 'some_app -d -f <files>'

如果你只给它一个 python 文件，它假定它是一个特殊的预检脚本。这些是用 python 编写的，可以访问应该转换的样式信息和文件。

这是一个预检脚本的基本示例，它将样式定义中“附加到文件”字段中给出的文本附加到文件末尾：

from pandoc_styles import run_preflight_script, file_read, file_write


def preflight(self):
    text_to_append = self.cfg["append-to-file"]
    if isinstance(text_to_append, list):
        text_to_append = "\n".join(text_to_append)
    file_write(self.files[-1], f"{file_read(self.files[-1])}\n{text_to_append}")


if __name__ == '__main__':
    run_preflight_script(preflight)

仅修改 preflight 函数以包含您的代码。

并在您的样式定义中运行它：

Test-style:
  html:
    preflight:
      - append-to-file.py
    append-to-file: "Test"

处理 Sass

您可以指向应该用于 html 输出的 sass 文件，此脚本会为您将它们转换为 css 并在输出中使用它。此外，您可以定义 sass 文件中使用的变量并指定编译后的 css 文件应该复制到哪里。

Test-style:
  html:
    sass:
      files: ~/default.scss
      output-path: temp
      variables:
        body-font-size: 10pt

“files”是要包含的 sass 文件的列表。

"output-path" 可以是 "~/" 输出到配置文件夹中的 css 文件夹，也可以是相对路径或 "temp" 与 "self-contained" 参数一起使用。如果省略，则 css 输出与源文件输出位于同一文件夹中。

“变量”可以是 sass 文件中的任何变量。

添加到模板

有时您希望将一些代码直接包含在模板中，而不是仅仅将其包含在标头中。大多数情况下，如果您想定义和使用自己的模板变量。

这个选项只是将给定的代码直接注入到模板的头部。

它接受文件的路径并将文件的内容添加到模板中。

Test-style:
  pdf:
    add-to-template:
      - |
        \titlehead{{$titletop-left$
        \hfill $titletop-right$\\}
        $titlehead$}
        \publishers{\small $titlebottom$}

在模板中替换

和上面一样，但不仅仅是将代码添加到头部，它会替换模板中的任意文本。你需要给它一个模式和一个替换文本。可选地，您可以使用标志“add”来不替换文本，但如果只替换一些匹配项，则在其前面加上“count”字段。

Test-style:
  html:
    replace-in-template:
      - pattern: \$body\$
        replacement-text: |
          <div class="content">
          $body$
          </div>

在输出中替换

与模板中的替换完全相同，但用于输出文件中的文本

飞行后

这些脚本在源转换后调用。与预检非常相似，但<files>它只接受一个<file>

一些应用程序：

Test-style:
  html:
    preflight:
      - 'some_app -d -f <files>'

自定义脚本：

from pandoc_styles import run_postflight_script, file_read, file_write


def postflight(self):
    text_to_append = self.cfg["append-to-output"]
    if isinstance(text_to_append, list):
        text_to_append = "\n".join(text_to_append)
    file_write(ffile, f"{file_read(ffile)}\n{text_to_append}")


if __name__ == '__main__':
    run_postflight_script(postflight)

Test-style:
  html:
    preflight:
      - append-to-output.py
    append-to-output: "Test"

筛选

该脚本包含一些功能，使编写过滤器更容易一些。

高级示例

如果使用数学，Pandocs 自包含标志不适用于 html，因为不能包含 mathjax。这种风格并不是真正独立的，但它允许包含所有 css 的单个文件。此示例使用此脚本中包含的 default.sass 文件。字体也只是引用而不是包含，以使文件大小更小。

对于 pdf 中的代码，它在代码块中引入了换行，并在字体中引入了连字。

此外，还显示了继承。

All:
  all:
    lang: en
  pdf:
    pdf-engine: "xelatex"

Math-document:
  inherits:
    - Code
  html:
    self-contained: true
    mathjax: true
    sass:
      files: ~/default.scss
      output-path: temp
    replace-in-template:
      - pattern: \$body\$
        replacement-text: |
          <div class="content">
          $body$
          </div>
      - pattern: \$table-of-contents\$
        replacement-text: |
          <div id="sidebar">
          <input class="trigger" type="checkbox" id="mainNavButton">
          <label for="mainNavButton" onclick></label>
          $table-of-contents$
          </div>
    replace-in-output:
      - pattern: (<\/head>)
        count: 1
        add: true
        replacement-text: |
          <link href="https://fonts.googleapis.com/css?family=Noto+Sans|Noto+Serif|Oswald" rel="stylesheet">
          <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/tonsky/FiraCode@1.206/distr/fira_code.css">
      - pattern: <script type="text\/javascript">\/\*\n\s+\*\s+\/MathJax\.js.*?<\/script>
        replacement-text: |
          <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS_CHTML-full" type="text/javascript"></script>

Code:
  all:
    highlight-style: tango
  pdf:
    monofont: Fira Code
    # allow code line break
    add-to-template:
      - |
        \usepackage{fvextra}
        \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,breakautoindent=true,commandchars=\\\{\}}
      - |
        \setmonofont[
          Contextuals={Alternate}
        ]{$monofont$}
        \makeatletter
        \def\verbatim@nolig@list{}
        \makeatother

命令行工具

使用以下命令可在命令行上使用一些附加工具：

pandoc-styles-tools

import 选项用于导入样式包。

一种工具可以合并样式并将新样式输出到文件中。

本地化工具将所有使用的资产复制到本地目录中，以拥有一个独立的项目文件夹。

创建样式包

要创建样式包，只需使用样式包的名称创建一个文件夹。在文件夹中放置一个包含样式定义和样式包名称的 yaml 文件。然后模仿配置文件夹来组织提供的文件。

在 yaml 文件中，使用“stylepack_name@path”链接到样式包内的文件。

创建文件夹的 zip（文件夹在 zip 中）并以您的样式包命名。