ctex-kit: the package collection behind Chinese LaTeX typesetting

A monorepo of packages, not a single document class

CTeX-kit is a collection of packages, scripts and resources for Chinese TeX users, providing typesetting infrastructure for Chinese LaTeX workflows. It is maintained by the CTeX community and gathers the results of several technical routes, with the stated goal of providing unified and dependable Chinese typesetting support under different TeX engines.

The repository structure makes the scope obvious. The tree holds a `ctex/` directory for the core Chinese document classes and packages, a `xeCJK/` directory for the XeLaTeX CJK support, and then a long tail of focused packages: `CJKpunct/` for punctuation compression, `xCJK2uni/` for legacy CJK encoding to Unicode mapping, `xpinyin/` for automatic pinyin annotation of Han characters, `zhnumber/` for Chinese number and date formatting, `zhlineskip/` for automatic line spacing adjustment in mixed Chinese and Latin text, `zhspacing/` for automatic spacing insertion on the LuaTeX route, and `zhmetrics/` plus `zhmetrics-uptex/` for Chinese font metrics and for upTeX specifically.

There are also `jiazhu/` for interlinear glosses, `gbk2uni/` as a GBK to Unicode conversion tool, `gbkmac/` for GBK encoding support on macOS, `zh-luatex/` for experimental LuaTeX Chinese support, and a `support/` directory holding shared build configuration. A top level `scripts/` directory and a `Makefile` provide the local task entry points.

So this is a monorepo. A user who only wants `ctexart` still ends up with the whole collection available, and a user who needs only pinyin annotation can take that package alone.

ctex and xeCJK carry the two engines

Two packages are labelled core. `ctex` is the Chinese document class and package collection, described as unifying font configuration, heading schemes and multi-engine adaptation. `xeCJK` is the CJK font management, character spacing and punctuation compression layer under XeLaTeX.

The split reflects how the work divides in practice. The document class is the user facing part: it decides the section heading scheme, the default font setup, the date and number formats, and it hides the differences between engines so the same document class works under more than one. The xeCJK layer is the machinery underneath, where font selection, spacing and punctuation handling actually happen.

The satellite packages then cover specific jobs. `CJKpunct` handles CJK punctuation compression and spacing adjustment. `zhnumber` formats Chinese numbers and dates. `xpinyin` adds pinyin annotation automatically to Han characters. `zhlineskip` adjusts line spacing in mixed Chinese and Western text, and `zhspacing` inserts spacing between Chinese and Western text on the LuaTeX route. `zhmetrics` provides the Chinese font metric files, with `zhmetrics-uptex` doing the same for upTeX.

The `xCJK2uni` package is the odd one out and worth flagging. It maps traditional CJK encodings to Unicode, which is a compatibility concern rather than a typesetting one. It exists because a large body of older Chinese documents and font data still uses those encodings, and the migration path runs through this package.

Every package is also published separately on CTAN, with the README linking a CTAN page and version badge for each one, so a user can install one package without taking the rest.

One document class, or the package on a standard class

Using the tool is two lines in the common case. The document class route:

\documentclass{ctexart}
\begin{document}
\end{document}

Or the package route on a standard class:

\documentclass{article}
\usepackage{ctex}
\begin{document}
\end{document}

The choice matters and is a real fork in the road. `ctexart` is a Chinese document class, so it brings its own heading scheme, its own defaults for spacing and punctuation and its own date and number conventions, and it is the right choice when the document is Chinese first. Loading `ctex` on top of `article` keeps the standard class structure and layers the Chinese typesetting behaviour onto it, which is the right choice when the document is a Western document that happens to contain Chinese.

The supported engines are named in the documentation: XeLaTeX, LuaLaTeX, pdfLaTeX paired with the CJK package, and upLaTeX. The recommendation is XeLaTeX or LuaLaTeX for the best experience. That recommendation is not a preference, since the older routes carry their own baggage, and the package list shows it in the split between `zhspacing` on the LuaTeX route and `zhmetrics-uptex` for upTeX.

For installation, the documentation notes that all packages are included in TeX Live and MiKTeX and normally need no manual installation. If you want the development version, you clone this repository instead.

l3build is the build and test system for every package

The project uses l3build as its build and test framework, and the documentation gives the three commands that matter. Running the ctex test suite:

cd ctex
l3build check

Running the xeCJK test suite:

cd xeCJK
l3build check

And generating the CTAN release package:

l3build ctan

The CI configuration runs on Ubuntu, macOS and Windows against the current TeX Live release, covering five test suites: ctex, xeCJK, zhnumber, CJKpunct and zhlineskip. That the core two packages dominate the test coverage is a reasonable reflection of where the complexity sits.

The top level `Makefile` wraps l3build with a naming convention: `make <verb>` is an alias for `<verb>-all`, `make <verb>-<pkg>` runs a verb for a single package such as `make check-xeCJK`, and the verbs are doc, unpack, ctan, check and clean. The Makefile comments record something useful about the cost of the test suite, noting that ctex through check-ctex runs in parallel across four engines in roughly eight minutes, while the older serial method took about twenty minutes, and that smaller packages usually finish in seconds.

The release flow is also documented in that file. `make tag <pkg>-v<ver>` creates a local tag without pushing, and after the tag is pushed, a GitHub Actions workflow automatically builds the CTAN package and creates a GitHub release.

Two other Makefile variables show how the project keeps itself honest. `L3BUILD_PKGS` lists the packages covered by the build, and `CHANGELOG_PKGS` lists the ones that carry `\changes` entries and a CHANGELOG.md, with a comment calling that list the single source of truth for the changelog check workflow.

The changelog is generated, and contributors have to run it

The contribution rules are unusually specific about the changelog, and the reason becomes clear once you know that the CHANGELOG files are generated rather than written by hand.

The documentation asks that, before submitting code, you ensure the relevant tests pass with `l3build check`, that you follow the expl3 programming conventions, and that changes to a `.dtx` file are recorded in `\changes`. Since the sources are literate, a `.dtx` file holds the code and its documentation together, and `\changes` is the standard LaTeX3 mechanism for recording what changed in a release.

The fourth rule is the operational one. After modifying `\changes`, you run `make changelog`, or the equivalent `cd <pkg> && python3 ../scripts/extract-changes.py "*.dtx" all -o CHANGELOG.md`, to regenerate the package's CHANGELOG.md and commit it alongside the change. The documentation adds a pragmatic fallback for contributors without Python locally, who can copy the expected content from the failing check-changelog CI log.

That mechanism explains why `CHANGELOG_PKGS` in the Makefile is a list rather than a convention. The comment says the packages that write `\changes` and maintain a CHANGELOG.md are named there, and that the rest of the packages have no `\changes` in their `.dtx` files, with CJKpunct, jiazhu and xCJK2uni named specifically. The check-changelog workflow runs `make changelog` directly, so a package that starts writing `\changes` has to be added to that list.

The wider technical stack is worth noting for anyone reading the source: the programming framework is LaTeX3 and expl3, the literate programming tool is docstrip with `.dtx` sources, the build system is l3build, and CI runs on GitHub Actions with both testing and automated publishing.

What the collection cannot do for you

The first limit is that this is a typesetting layer, not a document model. It handles fonts, spacing, punctuation and numbers. It does not decide what your document is about, and it does not give you a bibliography workflow, a table of contents generator or a cross reference system beyond what LaTeX itself provides. If your need is Chinese content management rather than Chinese typesetting, this is the wrong layer to start at.

The second limit is engine coverage. The documentation names four engines, but the satellite packages are not uniformly available on all of them. `zhspacing` is on the LuaTeX route, `zhmetrics-uptex` exists because upTeX needs its own metrics, and `zh-luatex` is described in the repository listing as experimental LuaTeX Chinese support. Working out which combination is actually supported for the engine you use is the practical work of adopting this, and it is work the package list makes possible but does not resolve for you.

The third limit is the version spread across the collection. The recent releases listed are all release candidates of xeCJK, with 3.10.7-rc4, rc3 and rc2 tagged within about ten days of each other in October 2026. A release candidate is fine for testing and unwise for a document you need to reproduce, so the choice between a stable install from TeX Live and a development checkout of this repository is a real decision rather than a formality. The last push was on 2026-10-13 and the repository is not archived.

The alternative approach is to use a single monolithic Chinese TeX distribution instead of picking packages from a collection. The difference in approach is granularity and maintenance: a distribution bundles a tested combination and takes on the work of making the pieces agree, while the collection gives you the individual packages with the versions they currently are, and leaves the compatibility matrix to you. For a document you are producing once, a distribution is less work. For a publishing setup where you pin and control versions, the collection plus l3build is the more controllable setup.

On licensing, the packages in this project are released under LPPL v1.3c, the LaTeX Project Public License, which is the standard licence for LaTeX packages.

Editorial conclusion

ctex-kit is the collection to reach for when a document mixes Chinese and Latin text, because the hard parts of that job, punctuation compression, inter-script spacing and line breaking rules, are handled by maintained packages rather than by ad hoc macros, and the ctex document class alone removes most of the setup. Do not adopt it for a purely Latin document, and do not expect a single engine to cover every package, since the documentation names XeLaTeX, LuaLaTeX, pdfLaTeX with the CJK package and upLaTeX, with the spacing package on the LuaTeX route and separate metric files for upTeX. Before you pin versions, check the release list, where the recent entries are release candidates of xeCJK 3.10.7, and note that the last push was on 2026-10-13, so a stable install from TeX Live and a development checkout of this repository can differ.

Frequently asked questions

Official sources

1. CTeX-org/ctex-kit on GitHub
2. Issues
3. Project website
4. README
5. Releases