Typst 数学排版指南

本页尚未完成新模型复核

本页保留旧版操作资料，不作为当前接口或产品能力的依据。课程/小节接口已移除，旧动画执行方式不再适用。新契约以前端接入流程为准；部署不得据旧文直接初始化已有数据库。

本指南专为数学讲义编者与教师编写。MakiMath 采用现代化排版语言 Typst，让你无需繁琐的环境配置，就能在网页上实时排版出清晰、美观的数学讲义。

数学公式语法：参考官方文档

Typst 的数学公式语法非常直观易懂，行内公式用一对单个 $ 包裹（如 $f(x)$），独立大公式用两边带空格的 $ 包裹。

有关数学符号、分数、上下标、根号、极限、积分、矩阵、分段函数等所有具体语法与写法，请直接查阅：

👉 Typst 官方数学参考手册 (Math Reference)

在官方手册中可以检索到每一个数学符号与函数的完整拼写和排版效果。

编写讲义的第一步：直接写内容

如果你之前用过本地 Typst 软件，可能会习惯在文档最开头写一堆页面大小、页边距、字体的代码。

在 MakiMath 中，请完全不要写这些！

// ❌ 不需要写任何类似下面的设置代码：
#set page(...)
#set text(...)
#import "@preview/..."

为什么不需要？

• 平台已经为你内置了精美的中英文字体和数学符号。
• 网页讲义会自动适应手机、平板和电脑屏幕，还会自动适配白天/夜间模式。
• 你在编辑器里，从第一行直接开始写你的标题、文字和公式即可。

那我该如何定义样式？

首先需要明确平台的一项基本规则：

所有 Typst 讲义都会自动匹配对应的“适配器”（决定你在讲义里写的哪个宏对应哪种卡片）和“样式”（决定这些卡片在页面上具体长什么样子）。

正因如此，你完全不需要在讲义开头写繁琐的代码。如果你希望为课程添加新的特色卡片（比如定理卡、定义框、例题卡、思考题等）或定制整体视觉风格，不需要懂编程，只需要准备以下三个文件并联系开发者协助配置：

1. 准备三个简单的文件：
   • 文件一：讲义示例（.typ）：展示实际讲义片段的正文内容，以及你在行文中如何调用这些卡片。
   • 文件二：样式参考（.typ 或参考图）：展示你期望的视觉外观（如边框颜色、底色、圆角、高亮效果或参考排版截图）。
   • 文件三：宏清单（.typ）：将你想使用的所有宏指令单独整理成一个完整清单，列出每个宏的名称、参数与用途。
2. 提交给开发者：
   • 将这三个文件打包发给平台技术团队，或在 GitHub 仓库提交 Issue。
3. 技术团队为你专属适配：
   • 开发者会依据你的宏清单和样式参考，在系统后台配置好适配规则，并做好手机端与深色模式适配。
   • 配置完成后，你在工作台中直接输入对应的宏指令名称即可实时渲染生效！

🌟 好消息：通用适配器与通用样式正在推进中

平台开发团队目前正在全力推进通用预设适配器（Universal Adapter）与通用数学样式表的建设！

未来平台将原生内置一套涵盖主流学科的基础数学卡片（如定理、定义、引理、例题、证明、推论等），实现开箱即用，届时新开设的常规课程无需再单独联系开发者定制基础卡片。敬请期待！

良好的排版习惯

• 中英文间距：数学公式、英文符号与中文字符之间，留一个空格读起来更舒服（例如：设函数 $f(x)$ 在点 $x_0$ 处可导）。
• 标点符号：正文文字使用中文全角标点（，。；），公式内部使用英文半角标点。