https://github.com/s15n/typst-thmbox
Modern, Friendly, and Customizable Theorem Environments for Typst
https://github.com/s15n/typst-thmbox
typst typst-package
Last synced: 4 months ago
JSON representation
Modern, Friendly, and Customizable Theorem Environments for Typst
- Host: GitHub
- URL: https://github.com/s15n/typst-thmbox
- Owner: s15n
- License: mit
- Created: 2025-02-01T17:31:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-15T11:44:36.000Z (about 1 year ago)
- Last Synced: 2025-06-15T12:28:34.086Z (about 1 year ago)
- Topics: typst, typst-package
- Language: Typst
- Homepage:
- Size: 347 KB
- Stars: 20
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Typst Thmbox
A typst package providing modern environments for theorems and proofs;
equipped with predefined variants for all common use cases but also
the flexibility to create custom ones with ease.
Built to easily write lecture notes with minimal setup.
## Usage
Before using any of the features this package has to offer, add the following lines to the top of your document:
```typ
#import "@preview/thmbox:0.3.1": *
#show: thmbox-init()
```
Now, the basic building block for thmbox environments is `thmbox`:
```typ
#thmbox[
This is a basic Thmbox
]
It can be referenced (see @basic-box).
```
Using the `color`, `variant`, and `title` parameters, we can style this box:
```typ
#thmbox(
variant: "Important Theorem",
title: "Fundamental Theorem of Math",
color: red
)[
A statement can only be believed if it is proven.
]
```
To prove this statement, we can follow up with a `proof`:
```typ
#proof[
Proven by obviousness.
]
```
---
For your environments, Thmbox actually ships with a variety of predefined ones, for theorems, corollaries, definitions, examples, etc:
Note that you don't need to specify the title parameter by name:
```typ
#definition[Typst][
Let Typst be the coolest typesetting system.
]
```
## Usage Notes
The recommended way of implementing new types of thmboxes is like this:
```typ
// derive from some predefined function
#let important = note.with(
fill: rgb("#ffdcdc"),
variant: "Important",
color: red,
)
#important[
This is in fact very important!
]
```
Of course, deriving from `thmbox` is just as good, but the predefined environments have some other parameters already set as well.
---
By default, the counter for thmboxes has two levels where the first one marks the chapter and the second gets reset at the start of each chapter.
To change that, use the `counter-level` parameter of `thmbox-init`. The default is 2, but for example, 1 will be one number counting in the entire document, 3 will count per section, and so on.
You can also use custom counters. Those must be registered with `sectioned-counter(, level: )` where level works just like `counter-level` mentioned above.
```typ
// Just some arbitrary custom counter
#let exercise-counter = counter("exercise")
// Register the counter for thmbox
#show: sectioned-counter(exercise-counter, level: 1)
// Use the counter
#let my-exercise = exercise.with(counter: exercise-counter)
#my-exercise[The first exercise!]
```
---
As set rules don't work with user-defined functions, a similar effect can be achieved the following way:
```typ
// Define your custom thmbox args
#let my-thmbox-rules = (
fill: rgb("#fffdd3")
)
// redefine predefined environments
#let my-definition = definition.with(..my-thmbox-rules)
// use
#my-definition[
This definition has a yellow background!
]
```
---
The recommended font for documents using this package is New Computer Modern (shipped with Typst).
The recommended sans-serif font (can be changed with the `sans-fonts` and `title-fonts` parameter) is New Computer Modern Sans (download at [CTAN](https://ctan.org/pkg/newcomputermodern))
By default, thmboxes don't break across pages. To enable that, you can use the rule `#show figure.where(kind: "thmbox"): set block(breakable: true)`. Other `set` and `show` rules for figures can be used with thmboxes as well, as figures are used under the hood.
## Installation
No steps are required when installing from `@preview`. To install this package [locally](https://github.com/typst/packages?tab=readme-ov-file#local-packages), do
```sh
cd /typst/packages/local/thmbox
git clone https://github.com/s15n/typst-thmbox.git 0.3.1
```
where `` is
- `$XDG_DATA_HOME` or `~/.local/share` on Linux
- `~/Library/Application Support` on macOS
- `%APPDATA%` on Windows
You might have to create the folder in the first line first.
## Translations
Thmbox automatically translates to the language of your document (if translations are available for it).
Translations are found in [src/translations.typ](https://github.com/s15n/typst-thmbox/blob/main/src/translations.typ). You are welcome to contribute for languages you speak.