Modern SWJTU Thesis

A modern Typst template for the thesis of Southwest Jiaotong University (SWJTU). > Note: The documentation and the template itself are primarily in Chinese.

西南交通大学学位论文 modern-swjtu-thesis

西南交通大学（SWJTU）本科毕业设计（论文）的 Typst 模板，基于南京大学的 modern-nju-thesis 进行二次开发，能够简洁、快速、持续生成 PDF 格式的毕业设计和论文任务书等文件。

当前阶段：本项目目前已经实现了本科生毕业设计（论文）（包括首末页、声明、版权页、任务书、评阅页、中英文摘要、目录及正文排版等），硕士研究生模板尚未开发。欢迎各位交大学子 PR 贡献代码！

缘起 (为什么有这个项目？)

大家好，我是西南交通大学（SWJTU）的一名本科生。

在准备毕设的过程中，我经常遇到 Word 排版不稳定、图片位置难以控制，以及传统 LaTeX 学习曲线陡峭、编译较慢等问题。后来我了解到南京大学 NJU-LUG 维护的 modern-nju-thesis Typst 模板，并被其简洁的语法和较快的编译速度吸引。

基于“他山之石，可以攻玉”的想法，我在 modern-nju-thesis 的基础上二次开发了适用于西南交通大学本科毕业设计（论文）的 Typst 模板。希望这个由学生自发维护的民间模板，能够减少排版工作带来的重复劳动，让大家把更多时间投入到论文内容本身。原西南交通大学模板可参考。

劣势

Typst 是一门较新的排版标记语言，生态仍在快速发展中，可能偶尔会遇到一些兼容性问题或缺陷。
该模板并非校方官方模板，而是我们交大学生自发维护的民间模板，提交前请务必和指导老师确认排版格式的合规性，可能存在最终打印格式不被认可的风险。

优势

Typst 是可用于出版的可编程标记语言，拥有变量、函数与包管理等现代编程语言的特性，注重于科学写作 (science writing)，定位与 LaTeX 相似。

语法简洁：上手难度接近 Markdown，文本源码阅读性较高，减少了大量反斜杠与花括号带来的阅读负担。
编译快速：Typst 采用增量的 Rust 编译引擎，无论是终端执行还是 VS Code 插件内都能较快完成渲染。
环境搭建极简：通常无需安装体积庞大的 TexLive，使用轻量级插件即可开始编辑和预览。
现代语言心智：原生支持中日韩字符，而且提供函数式闭包排版写法。

可以参考 Typst 中文文档网站迅速入门。

使用指南

样例论文及入口：查看项目目录下的 template/thesis.typ。你主要在这个文件里填空和书写即可。

本地编译（强烈推荐）

推荐使用 VS Code 搭配 Tinymist Typst 插件进行本地编写与实时双向预览。

克隆本仓库到本地。
安装字体：模板依赖于系统字体来进行国标和校标排版。请确保你的系统安装了以下字体：
- Times New Roman、Arial、Courier New (常用英文字体)
- SimSun、SimHei、KaiTi、FangSong (Windows 中文字体)
- Songti SC、Heiti SC、Kaiti SC (macOS 中文字体)
- Noto Serif CJK SC、Noto Sans CJK SC (开源中文字体)
- Source Han Sans SC (思源黑体)
用 VS Code 打开该文件夹。
打开 template/thesis.typ，安装好 Tinymist 插件后，点击右上角的预览按钮（或者快捷键）即可在侧边实时渲染。
或者在终端执行：
```
typst compile template/thesis.typ
```

目录结构简析

template/thesis.typ: 论文的主入口文件。所有的个人信息（题目、作者、班级、学号等）、各个核心章节的正文都在这里调用。如果要分多文件写论文，可以用 #include "章节1.typ" 的方式引入。
pages/: 存放了各个特定独立页面的模板函数，比如：
- bachelor-task-page.typ (西南交大的任务书排版实现)
- bachelor-evaluation-page.typ (西南交大的评阅/成绩单排版实现)
- bachelor-cover.typ (本科标准封面封面)
- ... (后续若有同学贡献硕士模板也会存在这里)
layouts/: 存放全局排版布局（用来控制正文字号、行距、多级标题的 mainmatter.typ 等）。

参与贡献

欢迎直接在 Issues 中提出你的想法或 Bug 汇报。
如果你已经整理或实现了硕士研究生相关格式，欢迎提出 PR，一起完善这个模板。

致谢 & 饮水思源

本项目核心排版逻辑和底层架构大量借鉴且修改自南京大学 Linux User Group (NJU-LUG) 开源的现代学位论文模板：

nju-lug/modern-nju-thesis

向原作者 OrangeX4 以及它的所有贡献者们致以诚挚的敬意。没有前辈们的工作，就没有本项目的基础。也感谢 Typst 中文开源社区的所有贡献者。

License

这个项目继续使用 MIT License 开源，欢迎有需要的同学使用。

注意：Web App 没有安装本地 Windows 或 macOS 所拥有的字体，所以字体上可能存在差异，推荐本地编辑！

PS: 虽然与 Overleaf 看起来相似，但是它们底层原理并不相同。Overleaf 是在后台服务器运行了一个 LaTeX 编译器，本质上是计算密集型的服务；而 Typst 只需要在浏览器端使用 WASM 技术执行，本质上是 IO 密集型的服务，所以对服务器压力很小（只需要负责文件的云存储与协作同步功能）。

VS Code 本地编辑（推荐）

在 VS Code 中安装 Tinymist Typst。
按下 Ctrl + Shift + P 打开命令界面，输入 Typst: Show available Typst templates (gallery) for picking up a template 打开 Tinymist 提供的 Template Gallery，然后从里面找到 modern-nju-thesis，点击 ❤ 按钮进行收藏，以及点击 + 号，就可以创建对应的论文模板了。
最后用 VS Code 打开生成的目录，打开 thesis.typ 文件，并按下 Ctrl + K V 进行实时编辑和预览。

特性 / 路线图

说明文档
类型检查
- 应该对所有函数入参进行类型检查，及时报错
全局配置
- 类似 LaTeX 中的 documentclass 的全局信息配置
- 盲审模式，将个人信息替换成小黑条，并且隐藏致谢页面，论文提交阶段使用
- 双面模式，会加入空白页，便于打印
- 自定义字体配置，可以配置「宋体」、「黑体」与「楷体」等字体对应的具体字体
- 数学字体配置：模板不提供配置，用户可以自己使用 #show math.equation: set text(font: "Fira Math") 更改
模板
- 本科生模板
  - 字体测试页
  - 封面
  - 声明页
  - 中文摘要
  - 英文摘要
  - 目录页
  - 插图目录
  - 表格目录
  - 符号表
  - 致谢
  - 任务书
  - 评阅页/成绩单
- 研究生模板 (尚未移植，欢迎 PR!)
  - 封面
  - 声明页
  - 摘要
  - 页眉
  - 国家图书馆封面
  - 出版授权书
- 博士后模板
编号
- 前言使用罗马数字编号
- 附录使用罗马数字编号
- 表格使用 1.1 格式进行编号
- 数学公式使用 (1.1) 格式进行编号
环境
- 定理环境（这个也可以自己使用第三方包配置）
其他文件
- 本科生开题报告
- 研究生开题报告

其他文件

还实现了本科生和研究生的开题报告，只需要预览和编辑 others 目录下的文件即可。

Q&A

我不会 LaTeX，可以用这个模板写论文吗？

可以。

如果你不关注模板的具体实现原理，你可以用 Markdown Like 的语法进行编写，只需要按照模板的结构编写即可。

我不会编程，可以用这个模板写论文吗？

同样可以。

如果仅仅是当成是入门一款类似于 Markdown 的语言，相信使用该模板的体验会比使用 Word 编写更好。

为什么我的字体没有正常显示？

这是因为本地没有对应的字体，这种情况经常发生在 macOS 的「楷体」显示上。

你应该安装系统字体，如 KaiTi、FangSong 等中文字体，然后再重新渲染测试即可。

你可以使用 #fonts-display-page() 显示一个字体渲染测试页面，查看对应的字体是否显示成功。

如果还是不能成功，你可以按照模板里的说明自行配置字体，例如

#let (...) = documentclass(
  fonts: (楷体: ((name: "Times New Roman", covers: "latin-in-cjk"), "KaiTi")),
)

先是填写英文字体，然后再填写你需要的「楷体」中文字体。

字体名称可以通过 typst fonts 命令查询。

如果找不到你所需要的字体，可能是因为 该字体变体（Variants）数量过少，导致 Typst 无法识别到该中文字体。

为什么 Typst 有很多关于字体的警告？

你会发现 Typst 有许多关于字体的警告，这是因为 modern-nju-thesis 加入了很多不必要的 fallback 字体，你可以自定义字体消除警告，先英文字体后中文字体，应传入「宋体」、「黑体」、「楷体」、「仿宋」、「等宽」。

#let (...) = documentclass(
  fonts: (楷体: ((name: "Times New Roman", covers: "latin-in-cjk"), "KaiTi")),
)

学习 Typst 需要多久？

一般而言，仅仅进行简单的编写，不关注布局的话，你可以打开模板就开始写了。

如果你想进一步学习 Typst 的语法，例如如何排篇布局，如何设置页脚页眉等，一般只需要几个小时就能学会。

如果你还想学习 Typst 的「参考」部分，进而能够编写自己的模板，一般而言需要几天的时间阅读文档，以及他人编写的模板代码。

如果你有 Python 或 JavaScript 等脚本语言的编写经验，了解过函数式编程、宏、样式、组件化开发等概念，入门速度会快很多。

我有编写 LaTeX 的经验，如何快速入门？

可以参考小蓝书和 FAQ。

一些常见问题：

如何在段落内加入行间数学公式以避免首行缩进？

目前 Typst 有哪些第三方包和模板？

可以查看 Typst Universe。

我个人推荐的包：

基础绘图：cetz
绘制带有节点和箭头的图表，如流程图等：fletcher
定理环境：theorion
伪代码：lovelace
带行号的代码显示包：zebraw
简洁的 Numbering 包：numbly
幻灯片和演示文档：touying
相对定位布局包：pinit
数学单位包：unify
数字格式化包：zero
写 LaTeX 数学公式：mitex
写原生 Markdown：cmarker
写 Markdown-like checklist：cheq
写 Markdown-like 表格：tablem

为什么只有一个 thesis.typ 文件，没有按章节分多个文件？

因为 Typst 语法足够简洁、编译速度足够快、并且 拥有光标点击处双向跳转功能。

语法简洁的好处是，即使把所有内容都写在同一个文件，你也可以很简单地分辨出各个部分的内容。

编译速度足够快的好处是，你不再需要像 LaTeX 一样，将内容分散在几个文件，并通过注释的方式提高编译速度。

光标点击处双向跳转功能，使得你可以直接拖动预览窗口到你想要的位置，然后用鼠标点击即可到达对应源码所在位置。

还有一个好处是，单个源文件便于同步和分享。

即使你还是想要分成几个章节，也是可以的，Typst 支持你使用 #import 和 #include 语法将其他文件的内容导入或置入。你可以新建文件夹 chapters，然后将各个章节的源文件放进去，然后通过 #include 置入 thesis.typ 里。

我如何更改页面上的样式？具体的语法是怎么样的？

理论上你并不需要更改 nju-thesis 目录下的任何文件，无论是样式还是其他的配置，你都可以在 thesis.typ 文件内修改函数参数实现更改。具体的更改方式可以阅读 nju-thesis 目录下的文件的函数参数。

例如，想要更改页面边距为 50pt，只需要将

#show: doc

改为

#show: doc.with(margin: (x: 50pt))

即可。

如果你阅读了那些函数的参数，仍然不知道如何修改得到你需要的样式，欢迎提出 Issue，只要描述清楚问题即可。

或者也欢迎加群讨论：943622984

该模板和其他现存 Typst 中文论文模板的区别？

其他现存的 Typst 中文论文模板大多都是在 2023 年 7 月份之前（Typst Verison 0.6 之前）开发的，当时 Typst 还不够成熟，甚至连 包管理 功能都还没有，因此当时的 Typst 中文论文模板开发者往往需要自行实现较多基础功能，容易造成 代码耦合度高、代码结构复杂、重复实现基础功能 与 难以自定义样式 等问题。

该模板是在 2023 年 10 ～ 11 月份（Typst Verison 0.9 时）开发的，此时 Typst 语法基本稳定，并且提供了 包管理 功能，因此能够减少很多不必要的代码。

PS：2025 年 2 月进行了 Typst 0.13 的迁移更新。

并且我对模板的文件架构进行了解耦，主要分为了 utils、pages 和 layouts 三个目录，这三个目录可以看后文的开发者指南，并且使用闭包特性实现了类似不可变全局变量的全局配置能力，即模板中的 documentclass 函数类。

我不是南京大学本科生，如何迁移该模板？

我在开发的过程中已经对模板的各个模板进行了解耦，理论上你只需要在 pages 目录中加入你需要的页面，然后更改少许、或者不需要更改其他目录的代码。

具体目录职责划分可以看下面的开发者指南。

开发者指南

template 目录

thesis.typ 文件: 你的论文源文件，可以随意更改这个文件的名字，甚至你可以将这个文件在同级目录下复制多份，维持多个版本。
ref.bib 文件: 用于放置参考文献。
images 目录: 用于放置图片。

内部目录

utils 目录: 包含了模板使用到的各种自定义辅助函数，存放没有外部依赖，且 不会渲染出页面的函数。
pages 目录: 包含了模板用到的各个 独立页面，例如封面页、声明页、摘要等，即 会渲染出不影响其他页面的独立页面的函数。
layouts 目录: 布局目录，存放着用于排篇布局的、应用于 show 指令的、横跨多个页面的函数，例如为了给页脚进行罗马数字编码的前言 preface 函数。
- 主要分成了 doc 文稿、preface 前言、mainmatter 正文与 appendix 附录/后记。
lib.typ:
- 职责一: 作为一个统一的对外接口，暴露出内部的 utils 函数。
- 职责二: 使用 函数闭包 特性，通过 documentclass 函数类进行全局信息配置，然后暴露出拥有了全局配置的、具体的 layouts 和 pages 内部函数。

参与贡献

在 Issues 中提出你的想法，如果是新特性，可以加入路线图！
实现路线图中仍未实现的部分，然后欢迎提出你的 PR。
同样欢迎 将这个模板迁移至你的学校论文模板，大家一起搭建更好的 Typst 社区和生态吧。

致谢

感谢 @atxy-blip 开发的 NJUThesis LaTeX 模板，文档十分详细，本模板大体结构都是参考 NJUThesis 的文档开发的。
感谢 @csimide 帮忙补充的 bilingual-bibliography。
感谢 HUST-typst-template 与 sysu-thesis-typst 等 Typst 中文论文模板。

License

This project is licensed under the MIT License.

modern-swjtu-thesis

Package Information

Preview

1. Get the package

2. Initialize from template

Version History

Modern SWJTU Thesis

西南交通大学学位论文 modern-swjtu-thesis

缘起 (为什么有这个项目？)

劣势

优势

使用指南

本地编译（强烈推荐）

目录结构简析

参与贡献

致谢 & 饮水思源

License

VS Code 本地编辑（推荐）

特性 / 路线图

其他文件

Q&A

我不会 LaTeX，可以用这个模板写论文吗？

我不会编程，可以用这个模板写论文吗？

为什么我的字体没有正常显示？

为什么 Typst 有很多关于字体的警告？

学习 Typst 需要多久？

我有编写 LaTeX 的经验，如何快速入门？

目前 Typst 有哪些第三方包和模板？

为什么只有一个 thesis.typ 文件，没有按章节分多个文件？

我如何更改页面上的样式？具体的语法是怎么样的？

该模板和其他现存 Typst 中文论文模板的区别？

我不是南京大学本科生，如何迁移该模板？

开发者指南

template 目录

内部目录

参与贡献

致谢

License