☰

pandoc 模板必须提供的最小“API”是什么

tag-icon • tag-icon pandoc
pandoc 模板必须提供的最小“API”是什么

我尝试定义自己的 pandoc 模板用于作业报告，结果发现很多“未定义控制序列”问题。我查看了默认模板，但它太过通用，很难真正理解。

我已经写好了这个，我不希望我的模板变得更加复杂（即没有条件），原因是我宁愿使用 \LaTeX 来指定高级排版选项（这就是它的目的）并尽量减少 YAML。

\documentclass[11pt]{article}

\usepackage{fontspec,xltxtra,xunicode}

\setmainfont[
    BoldFont={Fira Sans SemiBold}, 
    BoldItalicFont={Fira Sans SemiBold Italic}
]{Fira Sans Book}
\setmonofont[
    Contextuals={Alternate}
]{Fira Code Retina}

\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

\begin{document}
$body$
\end{document}

考虑到我已经提供了\tightlist命令，我想知道 pandoc 期望从我的模板中获得什么 API，即我需要定义哪些函数/命令才能让 pandoc工作。我会用纯 LaTeX 编写，但我还需要将这些文档上传到 GitLab 存储库，因此 markdown 是最简单的解决方案。

我还没有找到任何关于编写 pandoc 模板的好的“傻瓜”指南，所以如果有的话，请指出，我将不胜感激。

编辑：我提供的模板在使用 Pandoc 时会抛出错误（尽管可能是我的命令标志有问题：）pandoc -N --template=mytemplate.tex --pdf-engine=xelatex my_doc.md -o my_doc.pdf。我这样说是因为答案表明这个模板应该可以工作，但事实并非如此 :(

答案1

据我所知，目前没有文档提供完整的规范。部分原因是很多内容都取决于输入文档：如果愿意对输入做出某些假设，则可以降低复杂性。例如，\tightlist仅当文档包含此类列表时才需要，\usepackage{graphix}除非您在某处指定了图像或徽标，否则不需要，等等。默认模板还涉及意外位置（脚注）的逐字翻译、对其他语言的“i18n”支持、不同的 LaTeX 引擎（pdflatex vs. xelatex vs. lualatex）等等。模板尝试以合理的方式仔细处理所有可能的输入。从这个意义上讲，默认模板是已经最小。

处理简单的输入时，使用像您这样的模板应该完全没问题。遇到问题时，请扩展和修改该模板。如果您的输入足够简单，这将非常有效。

如果期望模板可以适用于任意复杂的 Markdown 文档，那么应该采用另一种方式：获取默认模板（通过pandoc -D latex > my-template.tex），并根据需要删除或替换内容。人们可能会删除与 Beamer 演示文稿有关的所有内容，而且，由于您似乎不喜欢 YAML，大多数 pandoc-template 检查（如）$if(…)$ … $endif$，通过放弃所有 xetex/luatex 检查来提交到特定的 LaTeX 引擎，并对所有打算使用的包进行硬编码。我的经验告诉我，这需要大量工作；我不推荐这样做。

第三个选项当然是处理 pandoc 的常用方式，并通过 YAML 文件和要包含在标题中的文件（通过-H）自定义输出。这样做的好处是，人们可以从 pandoc 默认模板的更新中获益，而不必将它们移植到自定义模板。通常情况下，这是最简单的方法，因此我推荐这种方法。

答案2

正如@tarleb 所说，您需要为文本所使用的功能包含适当的包/代码。

要复制您的示例，您根本不需要创建自定义模板；您可以使用默认模板中的变量来实现相同的目的，并将其添加到文档中的 YAML 前置内容中：

---
fontsize: 11pt
mainfont: Fira Sans Book
mainfontoptions:
- BoldFont={Fira Sans SemiBold}
- BoldItalicFont={Fira Sans SemiBold Italic}
monofont: Fira Code Retina
monofontoptions:
- Contextuals={Alternate}
---

相关内容