企业官网建设流程全解析

• 文档

本篇指南以 pandoc-latex-template 仓库中的 日语示例文档 为核心，完整拆解 Eisvogel 模板在日文（CJK）场景下的构建命令、YAML 元数据约定与模板源码层的字体处理机制。读完本文，你将掌握：为什么日语示例不设置lang变量、CJKmainfont等字体变量如何在 XeLaTeX 引擎下生效、如何把该方案复用到你自己的中/日文 Markdown 文档并规避常见环境坑。

一、示例文档：元数据骨架与占位正文

examples/language-japanese/document.md 是仓库为演示 CJK 排版能力而准备的一份"日语假文"（dummy text）文档。它由两部分构成。

YAML 元数据块

文档头部使用 pandoc 的 YAML metadata block 声明了五项元数据：

--- title: "よ派にへたひ素ヘムナフュてるあてっはれねね区露。巣擢" author: [むて絵ヤイヤ手津絵] date: "2017-02-20" subject: "Markdown" keywords: [Markdown, Example] ...

这些字段与 README.md 中介绍的元数据用法完全一致：title会进入页眉左侧与 PDF 元信息，author进入页脚左侧，date进入页眉右侧，keywords被 hypersetup.latex 写入 PDF 的pdfkeywords。仓库 CHANGELOG 中还记录了该假文曾被专门改进（“Improve Japanese dummy text”），说明这份文档承担着演示与回归测试的双重作用。

值得注意的是：这份示例没有设置lang字段。这一点并非疏漏，而是构建脚本中的刻意选择（详见下文第三节）。

正文结构

正文使用纯日文假文填充：一个#一级标题、一个##二级标题、多个自然段，以及一个有序列表。整篇没有英文内容，正是为了检验模板在"全日文环境"下的表现——包括标题字体、正文换行、段落缩进与列表排版。用一级/二级标题来验证 CJK 字体在不同字号层级下是否都能正确渲染。

二、构建命令全解析：为什么是 XeLaTeX + CJKmainfont

每个示例目录都带一个build.sh，examples/language-japanese/build.sh 全文仅两行：

# No lang option (-V lang=jp) here because Japanese unsupported in polyglossia. pandoc "document.md" -o "document.pdf" --from markdown --template "../../dist/eisvogel.latex" --syntax-highlighting idiomatic --pdf-engine "xelatex" -V CJKmainfont="HiraginoSans-W4"

逐段拆解这条命令：

为什么必须用 XeLaTeX

Eisvogel 模板默认面向 pdfTeX 引擎编译。pdfTeX 使用fontenc/inputenc（见 fonts.latex），对日文这类大规模 Unicode 字形的支持非常有限；而 fonts.latex 的分支逻辑显示，一旦检测到 xetex 或 luatex，模板会改走fontspec/unicode-math路线——这正是 XeLaTeX/LuaLaTeX 能够按字体名直接加载系统日文字体的基础。README 的示例预览表也把该示例明确标注为 "CJK Support (when using XeLaTeX)"。

字体的平台依赖

HiraginoSans-W4是 macOS 自带的 Hiragino Sans 字体族名，属于平台相关字体。在 Linux/Windows 或 CI 环境下未必存在——这正是 examples/build-examples.sh 把language-japanese与language-chinese列入跳过列表的原因（脚本注释写的是 "These examples are skipped because they don't run in CI builds (for now)"）。你在自己的机器上复现时，只需把-V CJKmainfont换成系统中已安装的日文字体即可（例如 Noto Sans CJK JP 等开源日文字体）。

三、模板源码侧：CJK 字体变量如何进入 LaTeX 世界

-V CJKmainfont=...只是把变量喂给模板，真正起作用的是模板内部的条件分支。整个模板按$if(CJKmainfont)$组织了一段独立于英文场景的字体逻辑。

xeCJK 分支（XeLaTeX 路径）

template-multi-file/font-settings.latex 中的核心代码：

$if(CJKmainfont)$ \ifXeTeX \usepackage{xeCJK} \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} $if(CJKsansfont)$ \setCJKsansfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKsansfont$} $endif$ $if(CJKmonofont)$ \setCJKmonofont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmonofont$} $endif$ \fi $endif$

要点：

• 三个字体变量分工：CJKmainfont（正文）、CJKsansfont（无衬线）、CJKmonofont（等宽），分别映射到 xeCJK 的\setCJKmainfont/\setCJKsansfont/\setCJKmonofont。CHANGELOG 记录（#328）明确说明后两者仅在同时提供了CJKmainfont时才会生效。
• CJKoptions透传：所有CJK*字体都可附带CJKoptions选项（如字重、字距调整），模板会原样展开到字体命令的方括号中。
• 引擎守卫\ifXeTeX：即使变量被误设，该分支也只会在 XeLaTeX 下加载，避免破坏 pdfTeX 编译。

另外，template-multi-file/passoptions.latex 在检测到CJKmainfont时会预先执行\PassOptionsToPackage{space}{xeCJK}，为 xeCJK 包开启空格处理选项；template-multi-file/common.latex 中还有一处联动：XeLaTeX + CJK 字体时，删除线命令\st会改用xeCJKfntef的\sout，因为soul包的删除线对 CJK 字符无效——这说明模板对 CJK 的适配是体系化的，不止字体一处。

LuaLaTeX 的平行路径

同一文件 font-settings.latex 也为 LuaLaTeX 准备了平行方案：通过luatexja-preset预设包和luatexja-fontspec的\setmainjfont实现日文排版。也就是说，如果你更习惯 LuaLaTeX，日语同样可以跑通，只是预设参数通过luatexjapresetoptions传入。中文示例与日语示例均选用 xelatex，主要基于示例脚本对引擎的一致选择。

语言元数据的写入

如果文档设置了lang，hypersetup.latex 会把它写入pdflang，方便 PDF 阅读器识别文档语言；document-metadata.latex 在启用 PDF 标准（PDF/A 等）时也会把lang写入\DocumentMetadata。这些机制对日语文档同样有效，前提是引擎与 babel 支持该语言代码。

四、为什么日语示例刻意省略lang变量

这是本示例最有信息量的一行注释：

# No lang option (-V lang=jp) here because Japanese unsupported in polyglossia.

language-chinese 的构建脚本 注释则更直接：

# No lang option (-V lang=zh) here because Chinese is unsupported in polyglossia and babel.

含义是：Eisvogel 模板在设置了lang时会加载 babel/polyglossia 语言包（见 common.latex 的 Babel 分支），但 babel 与 polyglossia 对日文/中文语言代码的支持并不完整，强制设置lang: ja（或-V lang=jp）反而可能触发缺包或排版错误。因此官方示例选择了"不设置 lang、只设置 CJK 字体"的稳妥路线。

对比 README.md 的 "Changing the Document Language" 一节：-V lang=en-GB、-V lang=de这类用法面向的是 babel 支持完善的西方语言。结论：处理日文（以及中文）时，优先省略lang、依靠 xeCJK 字体变量；只有确认你的 babel/引擎版本支持对应语言代码时，才考虑补充lang。

五、复用到自己的文档：一份可直接套用的 CJK 配置

结合示例与模板机制，你可以用两种方式为自己的日文 Markdown 开启 CJK 排版。

方式一：命令行变量（与官方示例完全一致）

pandoc your-document.md -o your-document.pdf \ --from markdown \ --template eisvogel \ --syntax-highlighting idiomatic \ --pdf-engine xelatex \ -V CJKmainfont="HiraginoSans-W4"

若需要无衬线/等宽 CJK 字体（依赖仓库较新版本模板，CHANGELOG #328 起支持）：

pandoc your-document.md -o your-document.pdf \ --pdf-engine xelatex \ -V CJKmainfont="Noto Sans CJK JP" \ -V CJKsansfont="Noto Sans CJK JP" \ -V CJKmonofont="Noto Sans Mono CJK JP"

方式二：写入 YAML 元数据

把字体变量放进文档头部，命令即可只保留引擎参数：

--- title: "我的日语文档" author: [示例作者] date: "2026-10-14" subject: "Markdown" keywords: [Markdown, Example, Japanese] # 不设置 lang，规避 babel/polyglossia 对日文支持不完整的问题 CJKmainfont: "HiraginoSans-W4" # CJKsansfont: "HiraginoSans-W3" # 可选 # CJKmonofont: "HiraginoSans-W4" # 可选 ...

pandoc your-document.md -o your-document.pdf --pdf-engine xelatex --template eisvogel

混排文档（日文 + 英文代码）的补充建议

Eisvogel 的英文正文默认使用 Source Sans/Source Code Pro（见 eisvogel-added.latex）。在 XeLaTeX 下，拉丁字体走fontspec路线、CJK 字符走 xeCJK 路线，两者互不干扰，因此日文正文与英文代码块可以共存——日语示例本身虽然没有英文内容，但同仓库的 font-unicode-font-fallback 示例 展示了同一套字体机制下多文种回退（fallback）的扩展能力。

六、环境准备与常见注意事项

1. LaTeX 发行版：需包含 XeLaTeX、xeCJK、fontspec、unicode-math等包。README 的 "Required LaTeX Packages" 一节建议安装texlive-full，或用texlive-latex-extra再通过tlmgr install补齐xecjk等缺失包。
2. 字体可用性：HiraginoSans-W4为 macOS 字体名。在 Linux 上请改用已安装的日文字体（如 Noto Sans CJK JP），否则 LaTeX 会报找不到字体的错误。
3. CI 限制：官方构建脚本 examples/build-examples.sh 会跳过language-chinese与language-japanese，原因即平台字体依赖，本地手动执行build.sh即可构建。
4. 模板来源：示例脚本引用../../dist/eisvogel.latex，该单文件发布版需从 release 归档获取（README 有明确提示）；若直接使用本仓库源码，应改用 template-multi-file 目录下的多文件模板，或先按 release 流程生成单文件版。

总结

日语示例看似只是一个假文文档，实则是 Eisvogel 模板 CJK 能力的最小闭环验证：XeLaTeX 引擎 +CJKmainfont字体变量 + xeCJK 分支逻辑，三者缺一不可；而省略lang的注释则揭示了 babel/polyglossia 对日文支持的边界。理解这条链路后，你可以轻松将同一方案复用到中文、日文乃至多文种混排文档，并在 Linux/macOS/CI 等不同环境下正确替换字体与引擎参数。

延伸阅读：模板字体分支源码见 template-multi-file/fonts.latex 与 template-multi-file/font-settings.latex；语言处理见 template-multi-file/common.latex；中文示例的等价配置见 examples/language-chinese/build.sh。

• 文档