https://github.com/rubixdev/typst-i-figured

Configurable figure numbering per section in Typst.
https://github.com/rubixdev/typst-i-figured

Last synced: 3 months ago
JSON representation

Configurable figure numbering per section in Typst.

Host: GitHub
URL: https://github.com/rubixdev/typst-i-figured
Owner: RubixDev
License: mit
Created: 2023-10-06T15:02:58.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2025-05-26T16:41:44.000Z (11 months ago)
Last Synced: 2025-07-04T07:06:00.606Z (10 months ago)
Language: Typst
Homepage: https://typst.app/universe/package/i-figured
Size: 627 KB
Stars: 26
Watchers: 2
Forks: 2
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # I figured

Configurable figure numbering per section.

## Examples

### Basic

Have a look at the source [here](./examples/basic.typ).

![Example: basic](./examples/basic.png)

### Two levels deep

Have a look at the source [here](./examples/level-two.typ).

![Example: two levels deep](./examples/level-two.png)

## Usage

The package mainly consists of two customizable show rules, which set up all the

numbering. There is also an additional function to make showing an outline of

figures easier.

Because the [`show-figure()`](#show-figure) function must internally create

another figure element, attached labels cannot directly be used for references.

To circumvent this, a new label is attached to the internal figure, with the

same name but prefixed with `fig:`, `tbl:`, or `lst:` for images (and all other

types of generic figures), tables, and raw code figures (aka listings)

respectively. These new labels can be used for referencing without problems.

> [!NOTE]

>

> When using this package with math equations, make sure you don't already have

> a numbering set for equations and instead specify it in the

> [`show-equation()`](#show-equation) call. Also see

> [#14](https://github.com/RubixDev/typst-i-figured/issues/14).

```typ

// import the package

#import "@preview/i-figured:0.2.4"

// make sure you have some heading numbering set

#set heading(numbering: "1.")

// apply the show rules (these can be customized)

#show heading: i-figured.reset-counters

#show figure: i-figured.show-figure

// show an outline

#i-figured.outline()

= Hello World

#figure([hi], caption: [Bye World.]) 

// when referencing, the label names must be prefixed with `fig:`, `tbl:`,

// or `lst:` depending on the figure kind.

@fig:bye displays the text "hi".

```

## Reference

### `reset-counters`

Reset all figure counters. To be used in a heading show rule like

`#show heading: i-figured.reset-counters`.

```typ

#let reset-counters(

  it,

  level: 1,

  extra-kinds: (),

  equations: true,

  return-orig-heading: true,

) = { .. }

```

**Arguments:**

- `it`: [`content`] — The heading element from the show rule.

- `level`: [`int`] — At which heading level to reset the counters. A value

  of `2` will cause the counters to be reset at level two _and_ level one

  headings.

- `extra-kinds`: [`array`] of ([`str`] or [`function`]) — Additional

  custom figure kinds. If you have any figures with a `kind` other than `image`,

  `table`, or `raw`, you must add the `kind` here for its counter to be reset.

- `equations`: [`bool`] — Whether the counter for math equations should be

  reset.

- `return-orig-heading`: [`bool`] — Whether the original heading element

  should be included in the returned content. Set this to false if you manually

  want to construct a heading instead of using the default.

**Returns:** [`content`] — The unmodified heading.

### `show-figure`

Show a figure with per-section numbering. To be used in a figure show rule like

`#show figure: i-figured.show-figure`.

```typ

#let show-figure(

  it,

  level: 1,

  zero-fill: true,

  leading-zero: true,

  numbering: "1.1",

  extra-prefixes: (:),

  fallback-prefix: "fig:",

) = { .. }

```

**Arguments:**

- `it`: [`content`] — The figure element from the show rule.

- `level`: [`int`] — How many levels of the current heading counter should

  be added in front. Note that you can control this individually from the

  `level` parameter on [`reset-counters()`](#reset-counters).

- `zero-fill`: [`bool`] — If `true` and assuming a `level` of `2`, a

  figure after a `1.` heading but before a `1.1.` heading will show `1.0.1` as

  numbering, else the middle zero is excluded. Note that if set to `false`, not

  all figure numberings are guaranteed to have the same length.

- `leading-zero`: [`bool`] — Whether figures before the first top-level

  heading should have a leading `0`. Note that if set to `false`, not all figure

  numberings are guaranteed to have the same length.

- `numbering`: [`str`] or [`function`] — The actual numbering pattern to

  use for the figures.

- `extra-prefixes`: [`dictionary`] of [`str`] to [`str`] pairs —

  Additional label prefixes. This can optionally be used to specify prefixes for

  custom figure kinds, otherwise they will also use the fallback prefix.

- `fallback-prefix`: [`str`] — The label prefix to use for figure kinds

  which don't have another prefix set.

**Returns:** [`content`] — The modified figure.

### `show-equation`

Show a math equation with per-section numbering. To be used in a show rule like

`#show math.equation: i-figured.show-equation`.

```typ

#let show-equation(

  it,

  level: 1,

  zero-fill: true,

  leading-zero: true,

  numbering: "(1.1)",

  prefix: "eqt:",

  only-labeled: false,

  unnumbered-label: "-",

) = { .. }

```

**Arguments:**

For the arguments `level`, `zero-fill`, `leading-zero`, and `numbering` refer to

[`show-figure()`](#show-figure).

- `it`: [`content`] — The equation element from the show rule.

- `prefix`: [`str`] — The label prefix to use for all equations.

- `only-labeled`: [`bool`] — Whether only equations with labels should be

  numbered.

- `unnumbered-label`: [`str`] — A label to explicitly disable numbering

  for an equation.

**Returns:** [`content`] — The modified equation.

### `outline`

Show the outline for a kind of figure. This is just the same as calling

`outline(target: figure.where(kind: i-figured._prefix + repr(target-kind)), ..)`,

the function just exists for convenience and clarity.

```typ

#let outline(target-kind: image, title: [List of Figures], ..args) = { .. }

```

**Arguments:**

- `target-kind`: [`str`] or [`function`] — Which kind of figure to list.

- `title`: [`content`] or `none` — The title of the outline.

- `..args` — Other arguments to pass to the underlying

  [`outline()`](https://typst.app/docs/reference/meta/outline/) call.

**Returns:** [`content`] — The outline element.

[`str`]: https://typst.app/docs/reference/foundations/str/

[`int`]: https://typst.app/docs/reference/foundations/int/

[`bool`]: https://typst.app/docs/reference/foundations/bool/

[`content`]: https://typst.app/docs/reference/foundations/content/

[`function`]: https://typst.app/docs/reference/foundations/function/

[`array`]: https://typst.app/docs/reference/foundations/array/

[`dictionary`]: https://typst.app/docs/reference/foundations/dictionary/

## Acknowledgements

The core code is based off code from [@PgBiel](https://github.com/PgBiel)

(`@PgSuper` on Discord) and [@aagolovanov](https://github.com/aagolovanov)

(`@aag.` on Discord). Specifically from

[this message](https://discord.com/channels/1054443721975922748/1088371919725793360/1158534418760224809)

and the conversation around

[here](https://discord.com/channels/1054443721975922748/1088371919725793360/1159172567282749561).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/rubixdev/typst-i-figured

Awesome Lists containing this project

README