English | 中文

A LaTeX template that conforms to the official formatting requirements for Tongji University undergraduate theses. Supports XeLaTeX / LuaLaTeX compilation, offers both minted and listings for code highlighting, and is compatible with both biblatex and bibtex citation backends. Continuously tested on Linux, macOS, and Windows via CI.

[!NOTE] A complete sample can be found in Template Output Sample Display (Full Version), in the PDF download link under “Assets” in the Release page or Overleaf Template PDF.

---

Quick Start

Method	Description
Overleaf	Use the Overleaf template directly — zero setup
Local	Install TeX Live 2026+, clone the repo, run make
GitHub Actions	Fork this repo, push to trigger CI, download PDFs from Artifacts

[!TIP] This template is tested against TeX Live 2026 in CI. If you encounter unexplained compilation errors locally, please first check and upgrade your TeX Live installation to 2026. Older TeX Live versions may ship package versions that are incompatible with this template.

Usage

Online Use

Using Directly via Overleaf Template

You can use this template directly via the Overleaf template link.

[!IMPORTANT] When using the Overleaf template, please check the compiler and main entry settings:

• Set main.tex as the main entry file, instead of other .tex files in the project (especially tongjithesis.cls or tongjithesis.sty);
• It is recommended to use the XeLaTeX or LuaLaTeX compilers, as some compilers (such as pdfLaTeX) are not supported by this template.

Importing This Repository on Overleaf

• Download this repository via Code | Download ZIP at the top of the repository home page file list;
• Open Overleaf;
• Upload the downloaded zip file to Overleaf by dragging and dropping.

Compiling in GitHub Actions

The project is configured with GitHub Actions in .github/workflows/*.yaml. Pushing code to a fork repository or a template-generated repository will trigger tests. You can obtain build artifacts for multiple platforms from the Summary | Artifacts section of the workflow run associated with the commit.

(Enable GitHub Actions by checking Settings | Actions | General | Allow all actions and reusable workflows)

Local Use

Installing TeX Distribution

We recommend installing TeX Live (Windows, Linux) or MacTeX (macOS) following the official quick install guide.

Building the Project

We recommend building the project via the command line. Alternatively, you can use the VS Code LaTeX Workshop plugin.

Command Line

Makefile (Linux/macOS)

make all                # compile main.pdf
make ENGINE=$ENGINE all # use $ENGINE (where $ENGINE=-xelatex or -lualatex) to compile main.pdf
make clean              # remove intermediate files
make cleanall           # remove all intermediate files (including .pdf)
make wordcount          # word count

Batchfile (Windows)

.\make.bat                # the same to "make.bat thesis"
.\make.bat thesis         # compile main.pdf
.\make.bat thesis $ENGINE # use $ENGINE (where $ENGINE=-xelatex or -lualatex) to compile main.pdf
.\make.bat clean          # clean all work files by latexmk -c
.\make.bat cleanall       # clean all work files and main.pdf by latexmk -C
.\make.bat wordcount      # wordcount
.\make.bat help           # read the manual

Using VS Code and LaTeX Workshop Plugin

Install the LaTeX Workshop plugin in VS Code, and then **open the root directory of this project directly** (i.e., the `tongji-undergrad-thesis` folder, not a parent folder, otherwise `.vscode/settings.json` will not take effect). Since we have configured the LaTeX Workshop plugin in `.vscode/settings.json`, you only need to: - Select the `main.tex` file; - Click the button with the $\TeX$ icon on the left sidebar; - Click `Recipe: latexmk (xelatex)` from the `Build LaTeX project` list to compile the `.pdf` file. Alternatively, the LaTeX Workshop plugin will automatically compile the file when you save it.

Using in Docker

For detailed usage, see [tongji-undergrad-thesis-env](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-env).

Template Configuration

Document Class Options

This template provides the following document class options, which can be configured in main.tex:

\documentclass[
  oneside,           % One-sided printing (default), use twoside for double-sided printing
  fullwidthstop=false, % Whether to replace Chinese period "。" with Western-style period "．", default is false
  fontset=fandol,    % Font set to use, default is fandol
  times=false,       % Whether to use Times New Roman font, default is false
  minted=true,       % Whether to use the minted package for code highlighting, default is true
]{tongjithesis}

Detailed option descriptions

##### Single/Double-Sided Printing Options - `oneside`: Single-sided printing (default) - `twoside`: Double-sided printing, adjusts page margins and binding line ##### Font Options - `fontset=fandol`: Use Fandol font set (default) - `fontset=adobe`: Use Adobe font set (requires Adobe fonts installation) - `times=false`: Use `newtx` package fonts (default) - `times=true`: Use Times New Roman font ##### Chinese Punctuation Options - `fullwidthstop=false`: Keep Chinese period "。" unchanged (default) - `fullwidthstop=true`: Replace Chinese period "。" with Western-style period "．"

Rendering Rare Characters

Due to the default use of the Fandol font in this template, support for rare characters such as names and specific terms might not be adequate. We provide the Adobe font set in the [`fonts`](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/tree/fonts) branch of our GitHub repository. You can download and install these fonts, and then use the `fontset=adobe` option in `main.tex` to use the Adobe font set: ```latex \documentclass[ oneside, fontset=adobe, % other options... ]{tongjithesis} ``` This modification will switch the rendering in the document to use the Adobe font set, enhancing support for rare characters. **Note**: Placing Adobe font files in the project's root directory and specifying the font path in `main.tex` is not always effective. Therefore, we recommend installing the Adobe fonts into the system font directory. Tests show that placing Adobe font files in the root directory of an Overleaf project and using LuaLaTeX for compilation works, but this method may slow down the compilation process.

Code Highlighting Options

This template provides two code highlighting solutions:

1. minted package (Python-based): Provides advanced syntax highlighting features, requires Python environment.
   • Enable by setting minted=true (default) in main.tex
   • Requires installation of Python and Pygments library (pip install pygments)
   • You need to add Python to the system PATH environment variable,
     • or specify the Python path in main.tex (see below)
   • Requires -shell-escape parameter during compilation (this template has added)
2. listings package (pure LaTeX): Does not depend on external programs, can be used in any environment.
   • Enable by setting minted=false in main.tex
   • No additional program installation required

If you do not want to install Python or encounter minted-related errors, you can change minted=true to minted=false in main.tex. When using minted=false, the template will automatically use the listings package to process all code, without requiring additional configuration.

Using minted but don't want to add Python to the PATH environment variable?

You can add a redirection to the Python path of the `minted` package in the `main.tex` file: ```latex \renewcommand{\MintedPython}{/path/to/your/python} ```

How to contribute to this project?

Please refer to the Contributing Guide.

Open Source License

This project uses the LPPL-1.3c license. See the LICENSE file for details.

Project History

• This project originated from YukuanHU’s undergraduate thesis, which was uploaded on May 24, 2019.
• Starting May 9, 2021, ganler enhanced the functionalities (project structure and platform compatibility) based on the original project and began maintaining it.
• As of May 12, 2022, skyleaworlder started contributing to the project, integrated it into TJ-CSCCG, and has continued to update and improve it. It has now become a comprehensive undergraduate thesis template.
• From April 2023, RizhongLin began contributing to and managing the project.
• April 2025 update, implemented key-value based class options, supporting more flexible configuration.

We deeply appreciate the efforts of these contributors, whose work has facilitated and assisted many students.

If you find this template helpful for your thesis or dissertation, we hope you will acknowledge and honor these contributors in your acknowledgements section.

Acknowledgements

We have learned a lot from excellent open-source projects from top universities:

• sjtug/SJTUThesis: makefile & batchfile contributions.
• stone-zeng/fduthesis: workflows enhancements.

Contact Information

# Python
[
    f'jiawei#@$.edu'.replace('#', '6').replace('$', 'illinois'),
    f'jgli22@$.edu.cn'.replace('$', 'm.fudan'),
    f'rizhong.lin@$.%'.replace('$', 'epfl').replace('%', 'ch'),
][-1]