HFUT Awesome Marp Slides

Overview

使用 HFUT Awesome Marp 主题快速创建专业的学术演示文稿。基于 Markdown 语法，支持多种布局、导航栏、代码高亮、数学公式等特性。

工程目录分析（Project-Aware Mode）

当用户的 PPT 工作目录中存在工程项目文件夹时，PPT 内容必须严格基于工程事实。

检测条件

生成 PPT 前，先扫描 PPT 工作目录（即用户指定的 ws_src/xxx/ 目录）下是否存在工程项目文件夹。识别标志：

标志文件	语言/框架
`Cargo.toml`	Rust
`package.json`	Node.js / 前端
`go.mod`	Go
`pom.xml` / `build.gradle`	Java
`CMakeLists.txt` / `Makefile`	C/C++
`pyproject.toml` / `setup.py` / `requirements.txt`	Python
`.sln` / `.csproj`	C# / .NET

如果检测到任何一个标志文件，立即进入 Project-Aware Mode。

Project-Aware Mode 工作流

code

检测到工程文件夹
  ↓
Step 1: 深度代码分析（必须先完成，再写任何 PPT 内容）
  ↓
Step 2: 建立事实清单（Fact Sheet）
  ↓
Step 3: 基于事实清单生成 PPT 内容
  ↓
Step 4: 逐页交叉验证

Step 1: 深度代码分析（强制）

在写任何一行 PPT 内容之前，必须完成以下分析：

•
读取项目元数据 — Cargo.toml / package.json / go.mod 等，提取：
- •项目名称、版本、作者、描述
- •所有依赖及其版本号（直接依赖，非传递依赖）
- •构建配置、feature flags
•
读取所有源代码文件 — 逐个读取 src/、lib/、app/ 等目录下的每一个源文件，提取：
- •模块结构和文件组织
- •核心数据结构（struct、class、interface 定义）
- •API 端点 / 路由定义
- •关键算法和业务逻辑
- •错误处理方式
•
读取配置文件 — config/、.env、*.yaml、*.toml 等
•
读取测试文件 — tests/、*_test.*、*.spec.*
•
读取文档 — README.md、docs/

硬性禁止：未读取的文件中的内容不得出现在 PPT 中。

Step 2: 建立事实清单

分析完成后，在生成 PPT 前必须先整理出事实清单（不写入文件，在生成过程中作为内部参照）：

code

事实清单示例：
- 项目名：webserver
- 语言：Rust 2021 Edition
- 核心依赖：tokio 1.36.0, serde 1.0.197, flate2 1.0.28, brotli 3.5.0, ...
- 模块：main.rs, request.rs, response.rs, config.rs, cache.rs, param.rs, util.rs, exception.rs
- 支持的 HTTP 方法：GET, HEAD, OPTIONS（代码依据：param.rs 中 ALLOWED_METHODS）
- 压缩算法：Gzip, Deflate, Brotli（代码依据：response.rs 中 compress 逻辑）
- 缓存策略：FIFO（代码依据：cache.rs 中 FileCache 实现）
- ...

每一条事实必须标注代码依据（文件名 + 具体位置）。

Step 3: 严格事实约束规则

以下规则在 Project-Aware Mode 下为强制执行，违反任何一条都是不可接受的：

规则	说明	违反示例
禁止编造技术栈	所有技术栈必须来自依赖文件	项目没用 Redis 却写"使用 Redis 缓存"
禁止编造功能	只写代码中实际实现的功能	代码没有 HTTPS 却写"支持 TLS 加密"
禁止编造架构	架构描述必须与代码模块结构一致	代码是单体却写"微服务架构"
禁止编造性能数据	性能数据必须来自项目文档/README	没有 benchmark 却写"QPS 达到 10 万"
禁止美化描述	不得将简单实现描述为复杂高级方案	FIFO 缓存却写"智能缓存淘汰策略"
代码展示必须真实	PPT 中的代码片段必须从源码中提取精简	不得凭空编写"示例代码"
禁止推测设计意图	只描述代码做了什么，不猜测为什么	不得写"考虑到高并发场景特别设计了..."

Step 4: 代码片段引用规范

PPT 中展示代码时：

•必须从实际源码中提取 — 可以精简（删除非关键行），但不能改变逻辑
•标注来源 — 在代码块上方或旁边说明来自哪个文件
•精简规则 — 提取核心逻辑，删除 import、日志、注释等非关键行，控制在 8 行以内（两栏）或 10 行以内（单栏）
•禁止凭空编写 — 不得为了"演示效果"编写项目中不存在的代码

无工程目录时的行为

如果 PPT 工作目录下没有检测到任何工程项目文件夹，则按照用户提供的文字描述正常生成 PPT，不受上述约束。

Quick Start

1. YAML Front Matter（必须）

yaml

---
marp: true
size: 16:9
theme: am_red          # 可选: am_red, am_blue, am_green, am_purple, am_brown, am_dark
paginate: true
headingDivider: [2,3]  # 二级/三级标题自动分页
footer: \ *作者名* *班级* *日期*
---

2. 基础结构

code

封面页 (cover_e)
  ↓
目录页 (toc_b)
  ↓
[章节过渡页 (trans) → 内容页 (navbar + 布局)] × N
  ↓
结束页 (lastpage)

Page Types Reference

封面页

Class	特点	适用场景
`cover_e`	左白右色三角，右上角校徽	最常用，答辩/汇报
`cover_a`	上色下白渐变，居中标题	简洁风格
`cover_b`	圆角矩形标题框	突出标题
`cover_c`	横向色带，左对齐	正式场合
`cover_d`	上色带下白	简约风格

cover_e 示例（推荐）：

markdown

<!-- _class: cover_e -->
<!-- _paginate: "" -->
<!-- _footer: ![](../hfut-badge/HFUT_Horizontal_name&badge_white.png) -->
<!-- _header: ![](../hfut-badge/HFUT_badge_white.png) -->

# 演示文稿标题

###### 副标题说明

汇报人：姓名
班级信息

目录页

markdown

<!-- _header: 目录<br>CONTENTS<br>![](../hfut-badge/HFUT_badge_white.png)-->
<!-- _class: toc_b -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

- [第一章标题](#页码)
- [第二章标题](#页码)
- [第三章标题](#页码)

章节过渡页

markdown

## 1. 章节标题

<!-- _class: trans -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

内容页（navbar + 布局）

markdown

## 1.1 小节标题
<!-- _header: \ ***文档标题*** **当前章节** *其他章节* *其他章节*-->
<!-- _class: navbar cols-2 fglass -->

<div class=ldiv>
左栏内容
</div>

<div class=rdiv>
右栏内容
</div>

导航栏语法： ***粗斜体*** 文档标题 | **粗体** 当前章节 | *斜体* 其他章节

结束页

markdown

<!-- _class: lastpage -->
<!-- _footer: "" -->
![ ](../hfut-badge/HFUT_Horizontal_name&badge.svg)
###### 感谢观看！

Layout Classes

两栏布局

Class	比例	div类
`cols-2`	50%-50%	`ldiv/rdiv` 或 `limg/rimg`
`cols-2-64`	60%-40%	同上
`cols-2-46`	40%-60%	同上
`cols-2-73`	70%-30%	同上
`cols-2-37`	30%-70%	同上

其他布局

Class	说明	div类
`cols-3`	三栏	`ldiv/mdiv/rdiv`
`rows-2`	两行	`tdiv/bdiv`
`pin-3`	品字型	`tdiv` + `ldiv/rdiv`

布局选择原则：

•pin-3 要求三个区域都有充足内容（每区至少 3-4 行文字），否则大量留白很丑
•内容较少时优先用 cols-2 或 cols2_ol_ci
•timg 不要只放一行标题——应放实质性内容（完整段落、带详细说明的引用块）
•总结/展望类页面通常内容偏少，优先选 cols-2 fglass 而非 pin-3

div 后缀说明：

•ldiv/rdiv/mdiv/tdiv/bdiv: 普通容器
•limg/rimg/mimg/timg/bimg: 内容居中（适合图片）

Style Classes

列表样式（可叠加）

Class	效果
`col1_ol_sq`	单列有序+方形序号
`col1_ol_ci`	单列有序+圆形序号
`cols2_ol_sq`	两列有序+方形序号
`cols2_ol_ci`	两列有序+圆形序号
`cols2_ul_sq`	两列无序+方形
`cols2_ul_ci`	两列无序+圆形

引用框颜色

Class	颜色	适用
`bq-blue`	蓝色	信息说明
`bq-red`	红色	警告/重要
`bq-green`	绿色	成功/正面
`bq-purple`	紫色	提示
`bq-black`	黑色	严肃内容

其他样式

Class	效果
`fglass`	毛玻璃效果列表框
`fixedtitleA`	固定标题（上对齐）
`fixedtitleB`	固定标题+底色背景
`footnote`	脚注样式
`caption`	图表标题

Image Syntax

markdown

![](img.png)              # 普通图片
![#c](img.png)            # 居中
![w:500](img.png)         # 宽度500px
![h:300](img.png)         # 高度300px
![#c w:500](img.png)      # 居中+宽度
![#c h:400](img.png)      # 居中+高度

图片占位符（重要）

生成 PPT 时图片往往还不存在，使用占位符模式：

markdown

## 小节标题
<!-- _class: navbar caption -->

<div class=rimg>

<!-- TODO: 替换为实际图片 img/architecture.png -->
![#c h:400](img/placeholder.png)

<div class="caption">
图1：系统架构图
</div>

</div>

占位符规范：

•使用  注释标记
•图片路径使用有意义的名称（如 architecture.png）
•必须写好 caption，说明图片内容
•用户后续只需替换图片文件，无需改代码

图表标题（关键）：

•必须在 _class 中加 caption 才能渲染 <div class="caption"> 的样式
•例如

markdown

<!-- _class: navbar caption -->

![#c h:400](img/diagram.png)

<div class="caption">
图1：系统架构图
</div>

单页内容上限（必读）

Marp 不会自动分页。内容超出页面会被裁切并覆盖脚注。必须严格控制每页内容量。

每页最大内容量

页面类型	上限	示例
单栏	正文总计 ≤10 行	1 个表格(≤5数据行) + 标题 + 引用块
两栏 (cols-2)	每栏 ≤8 行	标题 + 列表(≤5项) 或标题 + 小表格
含代码（单栏）	代码 ≤10 行	标题 + 代码块 + 简短说明
含代码（两栏）	代码 ≤8 行	标题 + 代码块

行数计算：标题行 + 列表项数 + 表格行数(含表头) + 代码行数 + 引用行数 = 总行数

硬性禁止

•同一页面或同一栏禁止放两个表格 — 几乎 100% 溢出
•两栏代码禁止超过 8 行 — 超出必须精简或拆页
•单栏代码禁止超过 10 行 — 超出必须精简或拆页

超出时如何拆页

将一页拆为两页，保持同一小节编号，用短横线加子标题区分：

code

## 3.2 Neo4j 存储 - 数据模型    ← 第一页
## 3.2 Neo4j 存储 - 查询示例    ← 第二页

写完每页必须验证

每写完一页，立即执行以下检查：

•数总行数（标题 + 列表 + 表格 + 代码 + 引用）
•单栏 > 10 行 → 必须拆页
•两栏任一栏 > 8 行 → 必须拆页
•出现两个表格 → 必须拆页
•宁可多一页留白，也不要少一页溢出

Best Practices

图片工作流（重要）

先写结构，后加图片：

•生成阶段 — 使用占位符  + 写好 caption
•用户准备图片 — 根据 caption 说明准备对应图片
•替换阶段 — 将图片放入 img/ 文件夹，删除 TODO 注释

图片数量要求：

•一份 20+ 页的 PPT 至少包含 5-6 张图片占位符
•适合放图的位置：整体架构图、数据流/流程图、实验结果图、系统截图/演示图、对比可视化图
•图片页通常用 cols-2-64 caption 或单栏 caption 布局，图片放在 rimg 或独立居中

为什么这样做：

•纯文字 PPT 信息密度高但视觉单调，图片提升表达力
•生成时图片通常不存在，用占位符标记
•caption 先写好确保图片内容明确
•用户只需替换文件，不需要改代码

页面组织

•每章开头用 trans 过渡页 — 给观众清晰的章节切换信号
•navbar 保持一致 — 同一章节内用相同的 header 导航
•合理使用 fglass — 列表内容配合毛玻璃效果更美观

内容布局

•图文并排用 cols-2-64 或 cols-2-46 — 文字多的一侧占大比例
•代码展示用 cols-2 — 左边代码，右边效果图/说明
•步骤说明用 col1_ol_ci + fglass — 有序列表+圆形序号
•对比内容用表格 — 清晰展示差异
•总结/展望页用 cols-2 fglass 或 cols2_ol_ci — 不要用 pin-3（内容通常不够填满三区域）
•引用框放实质内容 — > 引用块应包含总结性段落或详细说明，不要只写一行标题标签
•表格、列表、代码必须放 ldiv/rdiv，禁止放 limg/rimg — limg/rimg 使用 flexbox 居中，会压缩表格宽度导致列被截断；limg/rimg 仅用于图片
•两栏高度尽量平衡 — 若一栏内容明显少于另一栏，在较短一栏补充引用块（>）或额外说明文字，避免底部大片留白

内容密度

•每个 div 区域至少 3-4 行实质内容 — 太少则留白过多，显得空洞
•列表项用"粗体关键词+冒号+说明"格式 — 如 **知识蒸馏**：压缩模型体积，降低推理延迟
•避免裸列表 — 只写三五个短词条的列表看起来很单薄，补充解释或加引用块充实内容
•内容上限和拆页规则 — 见上方「单页内容上限」章节，每页写完必须验证行数

技术内容

•代码块指定语言 — ```verilog ```python 等
•关键代码配合说明 — 先文字解释，再代码展示
•波形/架构图配 caption — 标注图号和说明

信息密度

•每页一个核心观点 — 不要堆砌信息
•超过5条用两列布局 — cols2_ol_ci 或 cols2_ul_ci
•文字过多用 tinytext/smalltext — 保持可读性

Template: Academic Defense

markdown

---
marp: true
size: 16:9
theme: am_red
paginate: true
headingDivider: [2,3]
footer: \ *姓名* *班级* *日期*
---

<!-- _class: cover_e -->
<!-- _paginate: "" -->
<!-- _footer: ![](../hfut-badge/HFUT_Horizontal_name&badge_white.png) -->
<!-- _header: ![](../hfut-badge/HFUT_badge_white.png) -->

# 论文/项目标题

###### 副标题（课程名称/竞赛名称）

汇报人：姓名
指导老师：老师姓名

---

<!-- _header: 目录<br>CONTENTS<br>![](../hfut-badge/HFUT_badge_white.png)-->
<!-- _class: toc_b -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

- [研究背景](#3)
- [方案设计](#N)
- [实现细节](#N)
- [实验验证](#N)
- [总结展望](#N)

## 1. 研究背景

<!-- _class: trans -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

## 1.1 问题描述
<!-- _header: \ ***答辩标题*** **研究背景** *方案设计* *实现细节* *实验验证* *总结*-->
<!-- _class: navbar cols-2 fglass -->

<div class=ldiv>

**背景说明**

- 要点1
- 要点2
- 要点3

</div>

<div class=rimg>

<!-- TODO: 替换为实际图片 img/background.png -->
![#c h:400](img/background.png)

<div class="caption">
图1：问题示意图
</div>

</div>

<!-- 更多内容页... -->

## N. 未来展望
<!-- _header: \ ***答辩标题*** *研究背景* *方案设计* *实现细节* *实验验证* **总结**-->
<!-- _class: navbar cols-2 fglass bq-blue -->

<div class=ldiv>

**方向一标题**

- **关键词A**：具体说明，解释做什么、为什么
- **关键词B**：具体说明
- **关键词C**：具体说明

> 小结或目标说明

</div>

<div class=rdiv>

**方向二标题**

- **关键词D**：具体说明
- **关键词E**：具体说明
- **关键词F**：具体说明

> 小结或目标说明

</div>

---

<!-- _class: lastpage -->
<!-- _footer: "" -->
![ ](../hfut-badge/HFUT_Horizontal_name&badge.svg)
###### 感谢观看！

Common Mistakes

错误	正确做法
忘记 `<!-- _paginate: "" -->` 在封面/目录	特殊页面记得隐藏页码
div 类名拼错（如 `ldvi`）	检查 `ldiv/rdiv/limg/rimg`
图片路径错误	使用相对路径 `img/xxx.png`
navbar 语法错误	注意 `\` 开头，星号数量
class 组合顺序	navbar 放前面，布局放后面
忘记 fglass	列表内容加 fglass 更美观
pin-3 内容太少，大量留白	pin-3 每个区域需 3-4 行以上，否则换用 cols-2
`>` 引用块只写一行标题	引用块应包含实质段落，不要当标签用
列表项太短太裸	用 `关键词：说明` 格式充实每一条
内容超出页面被裁切	宁可拆成两页，不要硬挤。单栏 ≤12 行，每栏 ≤10 行
同一页/栏放两个表格	几乎必然溢出，必须拆成两页
两栏中代码块超过 8 行	两栏代码 ≤8 行，单栏 ≤10 行
`<div class="caption">` 无效果	必须在 `_class` 中加 `caption` 才能渲染图注样式
两栏表格放在 `limg/rimg` 中	`limg/rimg` 是 flexbox 居中，会压缩表格列宽导致截断；表格必须用 `ldiv/rdiv`
两栏高度严重不平衡，底部大片留白	较短一栏补充引用块或说明文字平衡高度
有工程目录却编造技术栈/功能	必须先深度分析代码，所有内容基于事实清单
代码片段是凭空编写的	必须从实际源码提取精简，标注来源文件
写了项目未实现的功能	只描述代码中确实存在的功能，不美化不推测

File Organization

code

your-ppt/
├── hfut-awesome-marp.md    # 主文件
├── img/                     # 图片文件夹
│   ├── architecture.png
│   ├── result1.png
│   └── ...
└── your-project/            # [可选] 工程项目文件夹
    ├── Cargo.toml / package.json / ...
    ├── src/
    └── ...

图片命名建议： 使用有意义的名称如 architecture.png、workflow.png，而非 image1.png

工程目录说明： 如果用户在 PPT 目录下放入了工程项目文件夹，自动进入 Project-Aware Mode（见上方「工程目录分析」章节）

Class	倍率
`tinytext`	0.8x
`smalltext`	0.9x
`largetext`	1.15x
`hugetext`	1.3x

HFUT Awesome Marp Slides

Overview

工程目录分析（Project-Aware Mode）

检测条件

Project-Aware Mode 工作流

Step 1: 深度代码分析（强制）

Step 2: 建立事实清单

Step 3: 严格事实约束规则

Step 4: 代码片段引用规范

无工程目录时的行为

Quick Start

1. YAML Front Matter（必须）

2. 基础结构

Page Types Reference

封面页

目录页

章节过渡页

内容页（navbar + 布局）

结束页

Layout Classes

两栏布局

其他布局

Style Classes

列表样式（可叠加）

引用框颜色

字体大小

其他样式

Image Syntax

图片占位符（重要）

单页内容上限（必读）

每页最大内容量

硬性禁止

超出时如何拆页

写完每页必须验证

Best Practices

图片工作流（重要）

页面组织

内容布局

内容密度

技术内容

信息密度

Template: Academic Defense

Common Mistakes

File Organization