Usage

To get started, add the following to your .typ file:

#import "@preview/ergo:0.2.0": *

#show: ergo-init

Example

#defn[Group][
  A *group* is an ordered pair $(G, star)$, where $G$ is a set and $star$ is a binary operation on $G$ satisfying
  1. _Associativity:_ $(a star b) star c = a star (b star c) forall a, b, c in G$
  2. _Identity:_ $exists e in G "such that" e star a = a star e = a forall a in G$
  3. _Invertibility:_ $forall a in G exists a^(-1) in G "such that" a star a^(-1) = a^(-1) star a = e$
]

#thm[Orbit-Stabilizer Theorem][
  Let $G$ be a group acting on a set $X$, with $x in X$.
  Then the map
  $
    G \/ G_x &-->              G dot x \
    a G_x    &arrow.r.bar.long a dot x
  $
  is well-defined and bijective, and therefore $|G dot x| = [G : G_x]$.
][
  Let $a, b in G$.
  Then
  $
    a G_x = b G_x
    &<==> b^(-1) a in  G_x \
    &<==> b^(-1) a dot x = x \
    &<==> a dot x  = b dot x.
  $
  Observe the map is well-defined by $(==>)$ and injective by $(<==)$.

  For surjectivity, note for any $a in G$, $a dot x$ is the image of $a G_x$.
]

Gallery

Real Analysis Notes using the bootstrap color scheme with the sidebar1 style

Cryptography Problem Set using the primer-light color scheme with the tab2 style

Classical Mechanics Notes using the woodland color scheme with the sidebar1 style (with Physica)

Abstract Algebra Notes using the terracotta color scheme with the basic style (with Fletcher)

Data Structures and Algorithms Notes using the dracula color scheme with the classic style (with CeTZ and Lovelace)

Refer to gallery/ for more examples.

Environments

Ergo has two different types of environments: solutions and statements.

The arguments are all positional, but name is optional, meaning either of these work:

// no `name` given
#theorem[ statement ][ proof ]

// `name` given
#theorem[ name ][ statement ][ proof ]

If you wish to state a result without giving a proof, you can leave proof as an empty content block [].

All of these environments (regardless of type) share a set of (optional) keyword arguments, including width (default: 100%) and height (default: auto), along with several other settings listed below.

Also, the problem environment includes an automatic counter if no title is passed in, which can be helpful when working on homework assignments.

If these environments aren’t enough, ergo-solution and ergo-statement are used to define all of these presets in src/presets.typ, and are exposed functions, so you can define your own presets.

Note that you will have to define colors for these new environments, which is detailed below in the Custom Color Schemes section.

Themes and Colors

A list of environment settings to customize your environments exists globally (resp. locally) which can be accessed by passing in keyword arguments to ergo-init (resp. the environment called). The valid arguments are the following:

• colors (default: ergo-colors.bootstrap) — colors of theme (refer to Color Palettes table for valid arguments)
• styles (default: ergo-styles.tab1) — style of theme (refer to Styles table for valid arguments)
• breakable (default: false) — whether the environments are breakable across page boundaries
• inline-qed (default: false) — whether the Q.E.D square is inline or right aligned in proof environments (only affects solution type environments)
• prob-nums (default: true) — whether problem environments have a numbering system (only affects problem)

#import "@preview/ergo:0.2.0": *

// global example
#show: ergo-init.with(
    colors:     ergo-colors.lime,
    styles:     ergo-styles.sidebar2,
    breakable:  true,
    inline-qed: true,
    prob-nums:  false,
)

// local example (takes precedence over global)
#prob(
    colors:     ergo-colors.bootstrap,
    styles:     ergo-colors.tab1,
    breakable:  false,
    inline-qed: false,
    prob-nums:  true,
)[ #lorem(5) ][ #lorem(10) ][ #lorem(10) ]

Color Palettes (values for colors)

ergo-colors.bootstrap (light)	Color scheme adapted from the CSS framework Bootstrap	No preview available
ergo-colors.bw (light)	Monochrome black and white scheme	No preview available
ergo-colors.equilibrium-gray-light (light)	From the Equilibrium Gray Light vim color scheme by Carlo Abelli
ergo-colors.penumbra-light (light)	From the Penumbra Light vim color scheme by Zachary Weiss
ergo-colors.primer-light (light)	From the Primer Light vim color scheme by Jimmy Lin
ergo-colors.measured-light (light)	From the Measured Light vim color scheme by Measured
ergo-colors.terracotta (light)	From the Terracotta vim color scheme by Alexander Rossell Hayes
ergo-colors.dracula (dark)	Adapted from dracula
ergo-colors.gruvbox-dark-medium (dark)	Adapted from the dark version of the famous vim color scheme gruvbox
ergo-colors.eighties (dark)	From the Eighties vim color scheme by Chris Kempson
ergo-colors.lime (dark)	From the Lime vim color scheme by limelier
ergo-colors.woodland (dark)	From the Woodland vim color scheme by Jay Cornwall

This function should be called before any content is rendered to enforce consistency of the document content.

Custom Color Schemes

You can also define your own color scheme. To do this, define a Typst dictionary with the valid fields and pass it in to the ergo-init function. One way to do this is to define your scheme with json:

#import "@preview/ergo:0.2.0": *

#let my-custom-colors = json("my-custom-colors.json")
#show: ergo-init.with(colors: my-custom-colors)

Refer to existing color schemes in src/color/ for information on valid fields. We support RGB and RGBA in hex format (i.e. "#ffffff" or "#ffffffff"). Note that you can use our Python project to automatically generate ergo themes from arbitrary Base 16 color schemes like those found on Tinted Gallery.

If you want to define your own environments, you must add information for how to color it. This is done through the id positional argument in ergo-solution and ergo-statement. The id is used to match the value in the json file. If you want to add your own id, you will have to format it in the following way:

{
  ...,
  "custom-proof": {
    "type": "proof",
    "bgcolor1": "#ffffff",
    "bgcolor2": "#bbbbbb",
    "strokecolor1": "#000000",
    "strokecolor2": "#000000"
  },
  "custom-statement": {
    "type": "statement",
    "bgcolor": "#bbbbbb",
    "strokecolor": "#000000"
  },
  ...
}

Note the type is important here, as it determines which color values you will have to supply for this package to view your dictionary as a valid color scheme. If you want examples, check out tests/custom.json.

Custom Styles

Although more complicated, we do support custom styles.

#import "@preview/ergo:0.2.0": *

#show: ergo-init.with(styles: my-custom-styles)

You must pass in a dictionary with only the keys solution and statement. Their values should be functions with the following structure (return value should be content):

#let custom-solution(
  title,
  statement,
  proof-statement,
  colors,
  ..argv
) = { ... }

#let custom-statement(
  title,
  statement,
  colors,
  ..argv
) = { ... }

#let custom-styles = (
  "solution": custom-solution,
  "statement": custom-statement,
)

Refer to src/style/ for examples in our presets.

Extras

There are a few extra functions and macros that may be of interest:

• correction(body) — Content with red text, useful for correcting a previous assignment
• bookmark(title, info) — Add additional information with small box. Particularly useful for recording dates and times
• equation-box(equation) (eqbox(equation)) — Box an equation
• ergo-title-selector — A selector controlling the style of the blocks

Local Installation (MacOS / Linux)

1. Clone this repository locally on your machine.
2. Run setup.sh from the root of the project directory. This script symlinks the project directory to the Typst local packages directory. Refer to the Typst Packages repository for more information.

$ git clone https://github.com/EsotericSquishyy/ergo
$ cd ergo
$ chmod +x common/scripts/setup.sh
$ ./common/scripts/setup.sh

Testing

Test whether the installation worked by running the following commands in an empty directory:

$ cat <<EOF > test.typ
#import "@preview/ergo:0.2.0": *
#show: ergo-init
#defn[#lorem(5)][#lorem(50)]
EOF

$ typst compile test.typ

The installation is successful if the file compiled without errors and test.pdf looks like this: