Maki Notes

maki-notes 是一个面向中文数学讲义与课程演示文稿的 LaTeX 模板项目。仓库现在提供两套文档类入口：

• maki-notes.cls 基于 ctexbook 的书式讲义入口。
• maki-beamer.cls 基于 ctexbeamer 的演示文稿入口。

这两个入口共享同一层核心样式实现：

• maki-notes.sty 集中管理字体预设、主题色、数学命令、内容块和 TikZ 语义样式。
• beamerthememaki.sty 负责 Beamer 的 title page、outline、headline、footline 和 block 外观。

也就是说，当前仓库推荐的使用方式是：

\documentclass[...]{maki-notes}

或者：

\documentclass[...]{maki-beamer}

而不是把 .sty 单独当成一个轻量通用包到处插拔。

特性

• 基于 ctexbook 的中文讲义排版入口
• 基于 ctexbeamer 的中文课件排版入口
• Beamer 端把共享配色 theme= 和版式选择 layout= 分开开放
• 内置封面、章节标题、页眉页脚与数学环境样式
• 提供定义、定理、例题、真题、注释等讲义常用盒子环境
• 提供课程元信息、整页章节导读与章内导航
• 提供核心公式、方法提要、常见误区、考试关注等数学讲义专用块
• 提供研究条目导引、问题/猜想/claim/proof sketch、符号表与开放问题表
• 提供参考 beamer-example/ 设计的 Beamer 主题页、目录页与章节导航
• 提供左右图文绕排、页边侧题注与无边框页边批注
• 集成 TikZ、PGFPlots、tikz-3dplot 等绘图能力
• 自带示例文档和基础测试文档，便于二次开发和回归验证

文档入口

如果你希望看比 README 更完整的说明，建议直接从 docs/README.md 开始。docs/ 目录目前包含：

• docs/template-guide.md：模板总览、类选项、编译方式和维护建议
• docs/workflow-guide.md：课程元信息、章节导读、本章导航与数学讲义专用块
• docs/research-writing-guide.md：研究笔记元信息、条目导引、研究环境、符号表与开放问题表
• docs/beamer-guide.md：maki-beamer.cls 的接口、共享层关系与演示文稿建议写法
• docs/wrapfig-margin-notes.md：图文绕排、侧题注与页边批注
• docs/tikz-template-pages.md：TikZ 模板册、样式族、新增页面索引和源码手册入口

环境要求

• TeX Live，且可使用 xelatex
• latexmk
• make

项目默认通过 latexmkrc 指定 XeLaTeX：

xelatex -interaction=nonstopmode -file-line-error

快速开始

直接基于 example.tex 或 document2.tex 修改即可：

\documentclass[a4paper,12pt,oneside]{maki-notes}

\renewcommand{\LectureNotesTitle}{你的讲义标题}
\renewcommand{\CoverTitle}{你的讲义标题}
\renewcommand{\CoverAuthorBlock}{作者信息}
\renewcommand{\CoverFooterBlock}{日期或附注}

\begin{document}
\frontmatter
\MakeTitlePage
\tableofcontents

\mainmatter
\chapter{第一章}
讲义正文。
\end{document}

如果你希望切换跨平台字体预设或主题配色，可以直接在 \documentclass[...] 里传入：

\documentclass[
  a4paper,
  12pt,
  oneside,
  fontpreset=common,
  theme=default
]{maki-notes}

如果你希望把模板用成更完整的“数学讲义工作台”，可以在章节前后继续加上：

\SetCourseInfo{
  course={高等数学},
  term={2026 春},
  audience={考研数学},
  instructor={Maki},
  lecture={第 3 讲},
  date={2026-04-13}
}

\SetChapterInfo{
  subtitle={从定义到连续性},
  keywords={极限, 连续, 夹逼准则},
  prereq={函数与实数基础},
  goals={理解极限定义; 会判断连续性; 会使用夹逼准则}
}

\chapter{极限与连续}
\MakeChapterGuide{
  route={定义 -> 性质 -> 计算 -> 连续},
  formulas={\[\lim_{x \to x_0} f(x)=A\]},
  pitfalls={连续不必可导; 去心邻域条件不能漏写},
  methods={夹逼, 等价无穷小, 代数变形},
  examfocus={极限定义判断题, 连续性与分段函数}
}

详细写法见 docs/workflow-guide.md。

如果你希望把模板继续用成“数学研究笔记工作台”，可以写成：

\SetResearchInfo{
  project={紧算子与谱结构},
  area={泛函分析},
  author={Maki},
  created={2026-04-13},
  status={working draft},
  updated={2026-04-13},
  tags={compact operator, spectrum}
}

\chapter{紧算子谱笔记}

\SetEntryInfo{
  topic={Riesz--Schauder 结构},
  source={Reed--Simon I},
  sourcekey={reed-simon-1},
  updated={2026-04-13},
  tags={compact operator, Fredholm},
  objective={整理非零谱离散性的证明骨架}
}

\MakeEntryGuide{
  summary={当前条目整理紧算子非零谱离散性的证明结构。},
  dependencies={Fredholm alternative; compact perturbation},
  targets={补全非零谱特征值有限重数部分},
  blockers={resolvent 紧性的引理链还不够紧凑},
  nextsteps={核对 Kato 的表述; 补 lemma 的引用位置}
}

\DeclareSymbol{$\sigma(T)$}{算子 $T$ 的谱}

\begin{question}[更短证明链]
能否不调用最完整的 Fredholm alternative, 直接说明非零谱只能由有限重特征值组成?
\end{question}

\PrintSymbolIndex
\PrintOpenProblemIndex

详细写法见 docs/research-writing-guide.md。

如果你要写演示文稿, 建议直接从 beamer-demo.tex 开始：

\documentclass[
  aspectratio=169,
  fontpreset=common,
  theme=cobalt,
  layout=splitbar
]{maki-beamer}

\title{科学机器学习讲义}
\subtitle{Transformer, PINN 与共享样式层}
\author{Maki Notes Demo}
\institute{maki-beamer / maki-notes}
\date{2026-04-13}

\begin{document}
\MakeTitlePage
\makeoutline[本次内容]

\section{引言}
\begin{frame}{共享样式}
  \begin{keyformula}
    \[
      \mathcal L = \mathcal L_r + \mathcal L_b + \mathcal L_i
    \]
  \end{keyformula}
\end{frame}
\end{document}

完整说明见 docs/beamer-guide.md。

字体与主题预设

模板现在支持两组跨 notes / beamer 共享的类选项：

• fontpreset=common|auto|windows|macos|linux
• theme=default|ocean|forest|graphite|amber|berry|sandstone|cobalt|sage|ruby|midnight

maki-notes 还支持讲义答案模式：

• answers=true|false
• solutions=inline|appendix|hidden

默认值是：

• fontpreset=common
• theme=default
• answers=false
• solutions=inline

如果你在用 maki-beamer，还可以额外使用：

• layout=durham|minimal|splitbar

推荐写法：

\documentclass[
  a4paper,
  12pt,
  oneside,
  fontpreset=auto,
  theme=ocean,
  answers=true,
  solutions=appendix
]{maki-notes}

fontpreset

• common：默认预设，优先使用 TeX Live 自带或稳定可用的字体组合，跨平台最稳
• auto：按当前机器已安装字体自动选择最接近的平台预设
• windows：优先使用常见 Windows 中文字体，缺失时回退到 common
• macos：优先使用常见 macOS 中文字体，缺失时回退到 common
• linux：优先使用常见 Linux 中文字体，缺失时回退到 common

当前策略是：拉丁正文统一走更接近 Palatino 数学风格的正文字体栈，中文字体再按预设切换。这样可以避免旧版本里正文和数学字体风格不一致的问题。

theme

• default：当前仓库原有的默认配色
• ocean：偏蓝青，更轻快
• forest：偏绿灰，更沉稳
• graphite：偏墨灰与铜棕，更正式
• amber：偏琥珀与蓝灰，适合讲义封面和流程图
• berry：偏莓红与靛灰，层次更强但仍保持克制
• sandstone：偏砂岩与石板灰，更接近纸面笔记气质
• cobalt：偏钴蓝与青绿，更适合科学计算、机器学习和课程汇报
• sage：偏鼠尾草绿与灰蓝，适合推导页较多的稳态讲义
• ruby：偏暗红与蓝灰，层次更强，适合专题报告和强调性页面
• midnight：偏深蓝灰与冷色强调，适合正式汇报和结构图页

主题切换不会改变公开接口，只会改写现有的语义色位，例如 LogicColor、DefColor、ExColor、NoteColor 等。因此现有环境、TikZ 样式和页边批注会一起换色，但代码写法不需要变。

layout

• durham：默认版式，最接近 beamer-example/ 参考设计
• minimal：减少装饰条和导航干扰，更适合内容密集型数学课件
• splitbar：强调顶部导航与信息分栏，更适合课程讲授和结构图页

可以把它理解成：theme= 管配色，layout= 管 Beamer 的页面骨架。

answers 与 solutions

solution 环境用于给 exercise 配套写答案。默认 answers=false 时答案内容不输出，适合学生版讲义。

\begin{exercise}[极限计算]
\label{ex:limit}
计算 \(\lim_{x\to 0}\frac{\sin x}{x}\).
\end{exercise}

\begin{solution}
由基本极限可得结果为 \(1\).
\end{solution}

• answers=true,solutions=inline：答案直接显示在题目后
• answers=true,solutions=appendix：答案先收集，调用 \PrintSolutions 时统一输出
• solutions=hidden：即使开启 answers=true 也不显示答案

常用中文引用命令包括 \chapref、\secref、\thmref、\defref、\exref、\exerciseref、\figref、\tabref 和 \eqnref。

回退与报错

• 如果你选中了某个平台预设，但本机缺少对应字体，模板会自动回退到 common
• 如果你显式写了不支持的值，例如 fontpreset=desktop 或 theme=sunset，模板会抛出清晰错误并指出合法取值

TikZ 预设族

宽图可以用 \MakiFitTikZ[<width>]{...} 缩放到指定宽度，避免横向溢出：

\MakiFitTikZ[0.8\linewidth]{%
\begin{tikzpicture}
  \node[flow process] {步骤};
\end{tikzpicture}%
}

模板里的 TikZ 样式不是零散颜色片段，而是按语义整理好的预设族。默认主题切换后，这些样式会自动跟随新的色位，不需要额外改图代码。

当前内置的预设主要包括：

• 神经网络与深度学习：nn input、nn hidden、nn output、nn tensor、nn op、nn skip
• Transformer：transformer token、transformer attention block、transformer norm、transformer ffn、transformer residual
• PINN / fPINN：pinn physics、pinn boundary、pinn initial、pinn total、fpinn operator、fpinn quadrature、fpinn memory
• 数学与几何：math axis、math curve、math tangent、math vector、geom point、geom angle mark
• 三维球面：sphere shell、sphere longitude、sphere latitude、sphere tangent plane、sphere vector
• 拓扑与流形：topo patch、topo identify、topo geodesic、manifold patch、manifold geodesic、manifold chart、manifold map accent
• 交换图：diag object、diag object accent、diag morphism emph、diag morphism natural、diag 2cell
• 傅里叶与信号图：fourier axis、fourier signal、fourier spectrum、fourier guide、fourier window
• 流程图：flow terminal、flow process、flow decision、flow io、flow arrow
• 时间轴：timeline axis、timeline event、timeline milestone、timeline span
• 概率/集合图：prob universe、prob event、prob event alt、prob condition、prob outcome
• 图论/网络图：graph node、graph node accent、graph edge、graph edge cut、graph walk

如果你想看完整可编译的组合示例，可以直接参考：

• 文档索引：docs/README.md
• 模板总览：docs/template-guide.md
• 样式测试页：tests/test-tikz-styles.tex
• 模板页：tikz-template-pages.tex
• 源码+渲染手册：tikz-example.tex
• 模板册说明：docs/tikz-template-pages.md

模板册新增页面索引

tikz-template-pages.tex 现在除了深度学习与拓扑页，也包含一组更偏“课堂讲义/报告结构图”的通用模板页：

• Transformer 编码器模板：适合注意力结构、编码器块和残差归一化流程
• PINN 结构模板：适合 PDE 残差、边界/初值条件和物理约束训练结构
• fPINN 结构模板：适合 fractional PINN 的非局部分支、历史项和离散算子示意
• 交换图与 pullback 模板：适合 pullback、自然变换、强调对象和背景范畴
• 三维球面与切平面模板：适合球面、经纬线、切平面和局部向量
• 局部流形图与坐标图模板：适合 patch、测地线、局部 chart 与坐标映射
• 傅里叶变换模板：适合时域/频域并排说明、窗函数和谱形示意
• 流程图模板：适合算法步骤、证明路线、实验流水线
• 时间轴模板：适合课程安排、项目里程碑、历史脉络
• 概率与条件事件模板：适合样本空间裁剪、条件概率和集合关系
• 图论与网络结构模板：适合最短路、最小割、网络流和搜索过程

如果你想按“该用哪组样式、该改哪些元素”来查，而不是直接翻 .tex 文件，可以看：

• docs/tikz-template-pages.md

这几组新样式也已经接进回归测试：

• tests/test-tikz-styles.tex 现在会同时覆盖 Transformer、PINN / fPINN、球面/流形、傅里叶时频图和交换图增强样式
• tikz-template-pages.tex 则提供对应的整页模板，适合直接复制改写
• tikz-example.tex 则把当前全部公开 TikZ 语义样式整理成“源码 + 实际渲染”的手册，适合按样式名查最小可复制示例

常用命令

make main
make example
make beamer-demo
make tikz-templates
make tikz-example
make smoke
make test
make clean

说明：

• make main：编译主示例 document2.tex
• make example：编译简化示例 example.tex
• make beamer-demo：编译 Beamer 示例 beamer-demo.tex
• make tikz-templates：编译 TikZ 模板页 tikz-template-pages.tex
• make tikz-example：编译 TikZ 源码+渲染手册 tikz-example.tex
• make smoke：编译最小烟雾测试文档 smoke-packaging.tex
• make test：编译烟雾文档和 tests/ 下的基础测试文档
• make clean：清理中间文件

图文绕排与页边批注

新版模板支持把图像贴在正文左侧或右侧自动绕排，并把图题或补充说明放到页面外侧边栏。相关接口已经整理到单独文档：

• 详细说明：docs/wrapfig-margin-notes.md
• 示例展示：example.tex
• 整合测试：tests/test-wrap-layout.tex

常用接口如下：

\begin{rightfiguretext}{0.36\textwidth}
  \centering
  \includegraphics[width=\linewidth]{figures/demo.pdf}
  \sidecaption{把图题放到页边。}
\end{rightfiguretext}

\sidenote{这里可以放一条无边框页边批注。}

还可以配合使用：

• leftfiguretext / rightfiguretext：左右图文绕排
• wrapcaption：图下题注
• sidecaption / sidecaptionof：页边题注
• sidenote / marginremark：页边批注

仓库结构

.
├── maki-beamer.cls
├── maki-notes.cls
├── beamerthememaki.sty
├── maki-notes.sty
├── latexmkrc
├── Makefile
├── beamer-example/
├── docs/
├── docs/beamer-guide.md
├── beamer-demo.tex
├── docs/workflow-guide.md
├── document2.tex
├── example.tex
├── tikz-template-pages.tex
├── smoke-packaging.tex
└── tests/

关键文件说明：

• maki-beamer.cls：Beamer 文档类入口，负责装配 ctexbeamer 与共享样式层
• maki-notes.cls：文档类入口，解析模板级类选项并加载样式包
• beamerthememaki.sty：Beamer 主题实现，负责标题页、目录页、页眉页脚与 block 风格
• maki-notes.sty：样式主体，集中管理字体预设、主题色、环境和 TikZ 样式
• beamer-demo.tex：Beamer 支持的完整演示文稿示例
• docs/beamer-guide.md：Beamer 接口、设计来源与使用建议
• document2.tex：较完整的讲义模板示例
• example.tex：更适合作为二次开发起点的示例文档
• docs/workflow-guide.md：课程元信息、章节导读与本章导航说明
• docs/wrapfig-margin-notes.md：图文绕排与页边批注用法说明
• docs/tikz-template-pages.md：TikZ 模板册结构与新增页面索引
• tikz-template-pages.tex：可直接复用的图形模板页
• tests/：用于验证模板基础能力的测试文档，其中 tests/test-basic.tex 覆盖类选项兼容，tests/test-beamer.tex 覆盖 maki-beamer 与共享内容层，tests/test-wrap-layout.tex 集中覆盖新版绕排与页边接口，tests/test-workflow-guide.tex 集中覆盖课程元信息与章节导读工作流，tests/test-solutions-inline.tex 与 tests/test-solutions-appendix.tex 覆盖答案输出模式

GitHub Release 流程

仓库中的 release workflow 位于 .github/workflows/release.yml，只会在推送 tag 时运行，不会在普通分支 push 时触发。

推荐使用语义化版本 tag，例如：

git tag v0.1.0
git push origin v0.1.0

workflow 会执行以下动作：

• 检出代码
• 用 XeLaTeX 编译讲义示例、Beamer 示例、TikZ 模板页、TikZ 源码手册和测试文档
• 打包一份包含 .cls / .sty、.tex 源码、beamer-example/、docs/ 说明和 tests/ 的源码发行包
• 调用 GitHub Models 生成 release notes
• 创建或更新与当前 tag 对应的 GitHub Release
• 上传编译后的 PDF 和源码包作为 release assets

日常 push 和 pull_request 会由 .github/workflows/test.yml 编译烟雾文档与测试文档，提前发现模板接口回归。

当前 release 资产包括：

• maki-notes-<tag>-source.tar.gz
• maki-notes-<tag>-manual.pdf
• maki-notes-<tag>-example.pdf
• maki-notes-<tag>-beamer-demo.pdf
• maki-notes-<tag>-tikz-templates.pdf
• maki-notes-<tag>-tikz-example.pdf

GitHub Models 自动化

仓库还提供了 3 个基于 GitHub Models 的自动化 workflow：

• .github/workflows/issue-model-comment.yml：在 issue opened 或 edited 时生成摘要并更新 issue 评论
• .github/workflows/pr-model-comment.yml：在 PR opened、reopened、ready_for_review 或 synchronize 时生成摘要并更新 PR 评论
• .github/workflows/release.yml：在 tag push 时生成 AI release notes

这些 workflow 默认使用 GitHub 自动注入的 ${{ secrets.GITHUB_TOKEN }}，不需要你手动保存或暴露 token。

对应权限如下：

• issue 评论：models: read + issues: write
• PR 评论：models: read + pull-requests: write
• release note 与发布：models: read + contents: write

当前 workflow 默认模型标识写的是 openai/gpt-5。如果你在 GitHub Models 页面看到的实际 slug 不同，需要同步改掉 workflow 里的 model 字段。

开发建议

• 修改模板能力时，先更新对应入口文件或共享样式层，再运行 make test
• 调整字体预设或主题配色时，优先验证 tests/test-basic.tex 的类选项编译结果
• 调整 Beamer 支持时，优先同步更新 docs/beamer-guide.md、beamer-demo.tex 和 tests/test-beamer.tex
• 新增展示内容时，优先放到 example.tex 或 tikz-template-pages.tex
• 调整图文绕排与页边批注时，优先同步更新 docs/wrapfig-margin-notes.md 和 tests/test-wrap-layout.tex
• 发布新版本时，只需要推送新的 tag；普通提交不会触发 release workflow