简介 {intro}

2026-03-12 02:59:08作者：侯霆垣

这是项目简介内容...

详细功能说明...

步骤说明...


3. **生成响应式HTML**
```bash
pandoc doc.md -o doc.html --template=responsive.html5 -s

进阶拓展：添加目录生成功能，在<nav>标签后插入：

$if(toc)$
<nav id="TOC" role="doc-toc">
  <h2>目录</h2>
  $table-of-contents$
</nav>
$endif$

使用时添加--toc参数即可自动生成目录。

案例3：多格式输出的统一模板方案（项目级）

目标：为开源项目创建一套模板系统，实现Markdown源文件一次编写，同时输出PDF、HTML和Word三种格式，保持一致的品牌风格。

项目结构设计：

project/
├── src/
│   └── manual.md       # 源文档
├── templates/
│   ├── common/         # 共享资源
│   │   ├── header.html # 通用页眉
│   │   └── footer.html # 通用页脚
│   ├── html/
│   │   └── custom.html5
│   ├── latex/
│   │   └── custom.latex
│   └── docx/
│       └── reference.docx
└── Makefile            # 构建脚本

实现步骤：

创建共享变量文件（metadata.yaml）

title: "项目使用手册"
author: "开发团队"
version: "1.2.0"
company: "开源项目社区"
copyright: "© 2024 开源项目社区"

设计HTML模板（templates/html/custom.html5）

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>$title$ v$version$</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css">
</head>
<body>
  <!-- 引入共享页眉 -->
  $include("templates/common/header.html")$
  
  <div class="container">
    $body$
  </div>
  
  <!-- 引入共享页脚 -->
  $include("templates/common/footer.html")$
</body>
</html>

设计LaTeX模板（templates/latex/custom.latex）

\documentclass{article}
\usepackage[margin=1in]{geometry}
\usepackage{hyperref}
\title{$title$ v$version$}
\author{$author$}
\date{}

\begin{document}
\maketitle
\tableofcontents
$body$

\vfill
\begin{center}
$copyright$
\end{center}
\end{document}

创建Word参考文档
```
pandoc -o templates/docx/reference.docx --print-default-data-file reference.docx
```
然后用Word编辑此文件，设置标题样式、字体和页眉页脚。

编写Makefile实现一键构建

# 定义变量
TEMPLATE_DIR = templates
SRC = src/manual.md
METADATA = metadata.yaml

# 构建所有格式
all: html pdf docx

# HTML格式
html:
  pandoc $(SRC) -o manual.html \
    --template=$(TEMPLATE_DIR)/html/custom.html5 \
    --metadata-file=$(METADATA) \
    -s --toc

# PDF格式
pdf:
  pandoc $(SRC) -o manual.pdf \
    --template=$(TEMPLATE_DIR)/latex/custom.latex \
    --metadata-file=$(METADATA) \
    -s --toc

# Word格式
docx:
  pandoc $(SRC) -o manual.docx \
    --reference-doc=$(TEMPLATE_DIR)/docx/reference.docx \
    --metadata-file=$(METADATA)

# 清理生成文件
clean:
  rm -f manual.html manual.pdf manual.docx

执行构建
```
make all
```
预期结果：生成manual.html、manual.pdf和manual.docx三个文件，保持一致的标题、版本号和版权信息

💡 高级技巧：使用 $include("path/to/file")$ 语法在模板中引入共享组件，避免重复代码。对于大型项目，可将CSS、JavaScript和LaTeX宏定义分离为独立文件，通过include机制组合。

三、变量系统：模板的"控制面板"

变量来源与优先级

Pandoc变量可通过多种方式定义，按优先级从高到低排列：

命令行参数：-V/--variable key=value
元数据文件：--metadata-file=FILE
文档内YAML块：位于Markdown文件开头的---分隔块
默认模板变量：Pandoc内置的预定义变量

核心变量分类与应用

变量类别	常用变量	应用示例
文档元数据	title, author, date	`pandoc -V author="张三, 李四"`
格式控制	toc, number-sections	`pandoc --toc -V number-sections`
样式设置	fontsize, geometry	`pandoc -V fontsize=12pt -V geometry=margin=1in`
自定义变量	company, version	在模板中通过 $company$ 引用

高级变量技巧：条件逻辑与循环

条件显示示例：

$if(version)$
<div class="version-badge">版本: $version$</div>
$endif$

$if(author)$
$for(author)$
<p class="author">$author$</p>
$endfor$
$else$
<p class="author">未知作者</p>
$endif$

循环与分隔符示例：

<ul class="keywords">
$for(keywords)$
  <li>$keywords$$sep$, $endfor$</li>
$endfor$
</ul>

$sep$ 会在列表项之间插入指定分隔符

⚠️ 注意事项：变量名称区分大小写， $Title$ 与 $title$ 是不同变量。建议统一使用小写字母加连字符的命名风格（如page-footer）。

四、常见问题与性能优化

模板调试与问题诊断

问题1：模板修改不生效

检查是否使用-s/--standalone选项（仅独立模式使用模板）
验证模板路径是否正确，可使用绝对路径测试
添加--verbose参数查看模板加载过程：pandoc --verbose -s --template=my template.md -o output.html

问题2：特殊字符显示异常

LaTeX模板：使用\textbackslash{}表示反斜杠，\$表示美元符号
HTML模板：使用<代替<，>代替>
通用方案：将特殊字符放在 $raw$ 块中：$raw$<script>$endraw$

问题3：中文字体显示乱码

在LaTeX模板中添加字体配置：

\usepackage{fontspec}
\setmainfont{SimSun}  % 宋体
\setsansfont{SimHei}  % 黑体

确保系统已安装相应字体，或使用--pdf-engine=xelatex引擎

模板性能优化策略

组件化设计：将模板拆分为多个小文件，通过$include()组合，减少重复代码

条件加载资源：仅在需要时加载外部资源

$if(highlighting)$
<link rel="stylesheet" href="highlight.css">
$endif$

缓存编译结果：对于大型文档，使用--cache-dir参数缓存中间结果
```
pandoc --cache-dir=.pandoc-cache large.md -o large.pdf
```

pandoc

Universal markup converter

项目地址：https://gitcode.com/gh_mirrors/pa/pandoc

登录后查看全文

项目优选

收起

Ascend Extension for PyTorch

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started

Rust

497

kernel

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。