Universe

Dynamic TOML Badge License: MIT

Synapse is a typst package offering an easy way to have every reference of a concept linked to its introduction throughout a document. This is heavily inspired by the knowledge package for LaTeX, but with a typst-like API.

Usage

This package relies on the concept of notion. A notion is a concept that can be introduced and referenced anywhere in the document. The reference will then all link to the introduction of the notion. To define a notion, you can use the notion function:

#notion("synapse")

This will define a notion called “synapse”. A notion can have synonyms, which are alternative names for the same notion. To define synonyms for a notion, simply add them as additional arguments to the notion function:

#notion("synapse", "synapses", "Synapse", "Synapses")

This will define the notion “synapse” with the synonyms “synapses”, “Synapse”, and “Synapses”. Now, whenever you reference any of these terms in your document, they will all link to the introduction of the notion.

To introduce a notion, you can use the intro function:

In the nervous system, a #intro("synapse") is a structure that allows a neuron to exchange (receive or send) signals with another cell in its immediate vicinity

Now, to reference the notion in the document (anywhere before or after the introduction), you can simply use the function syn followed by the name of the notion:

#syn("Synapses") are essential for the transmission of neuronal impulses from one neuron to the next, playing a key role in enabling rapid and direct communication by creating circuits. In addition, a #syn("synapse") serves as a junction where both the transmission and processing of information occur, making it a vital means of communication between neurons.

This will create a reference to the notion “synapse” and link it to its introduction.

The notion function also allows you to define an external link for a notion. To do this, simply add the url argument to the notion function:

#notion("synapse", url: "https://en.wikipedia.org/wiki/Synapse")

If an url is provided, you can’t use the intro function to introduce the notion, this will cause an error.

Notion Scoping

You can create distinct notions with the same display name by adding a % suffix to the synonym. For example:

#notion("set")  // General use
#notion("set%math")  // Mathematical use

Both notions will display as “set” in the document, but they are treated as separate concepts with independent introductions and links. This is useful when you want to use the same term with different meanings in the same document.

Quick reference with quotes

Writing the function calls every time can be a bit tedious. For this reason, the package also provides a show rule to automatically replace the name of the notion between quotes with the reference to the notion:

#show: quote-rule
"Synapses" are essential for the transmission of neuronal impulses from one neuron to the next, playing a key role in enabling rapid and direct communication by creating circuits. In addition, a "synapse" serves as a junction where both the transmission and processing of information occur, making it a vital means of communication between neurons.

This also works with introductions with par of double quotes on each side:

#show: quote-rule
In the nervous system, a ""synapse"" is a structure that allows a neuron to exchange...

Note: The quote rule matches text surrounded by exactly one pair of quotes ("text") for synonyms and exactly two pairs of quotes (""text"") for introductions.

By default, the link to the introduction of a notion is placed on the intro call. But you can change this by using the intro-ap function to define a custom anchor point. This can be useful if you want to place the link on a different part of the text, like for example at the beginning of the sentence:

#intro-ap("synapse") In the nervous system, a #intro("synapse") is ...

Now, the link to the introduction of the notion “synapse” will be placed at the beginning of the sentence instead of on the intro call.

The anchor point must be defined before the intro() call. In composition mode, a red marker indicates the anchor position.

Representation of the notion

intro and syn functions can also take an additional positional argument that will be used to represent the notion in the text. By default, the first synonym + styling is what is used to represent the notion. However, you can change this by providing a different argument. For example:


#notion("pi", "Pi")

#intro("pi", $pi$) is approximately equal to 3.14159...

This is quite useful for mathematical notions, where you often want to use a specific symbol to represent the notion. In this example, the notion “pi” is represented by the symbol $pi$ in the text. And you can easily do this:

#let pi = syn("pi", $pi$)

$
    sin(pi) &= 0 \
    cos(pi) &= -1 \
    tan(pi) &= 0 \
$

In this example, all the pi in the math expression will be linked to the introduction of the notion “pi” and will be represented by the typst symbol $\pi$.

Math functions

It is also possible to have math expression linked to a notion. To do this, you can use the syn-wrapper function. This function takes a function as parameter that should accept at least one argument, which will be used to create the link to the notion. For example, if you want to create an abs function where only the || are linked to the notion, you can do it like this:

#notion("abs")

#let abs = syn-wrapper("abs", (wrapper, value) => {
 $wrapper(|)value#wrapper($|$)$
})

#intro(abs, $x$) is a function that returns the absolute value of $x$.\
For instance, $abs(-5)$ will return $5$ while $abs(42)$ will return the exact same value of $42$.

Here the notion is introduced with intro like usual, but because abs takes one argument, the argument is passed to the intro function. Then any call to abs will behave like usual but with the || linked to the introduction of the notion “abs”. Note that the notion can still be used as text like normal so #syn("abs") will still work and link to the introduction of the notion “abs”. intro-ap will also behave like normal.

Styling

Synapse supports styling at three levels, from most specific to most general:

  1. Per-call styling: Use the style argument on individual intro() or syn() calls
  2. Per-notion styling: Define a style when creating the notion with notion()
  3. Global styling: Use synapse-config() to set default styles for all notions

The priority order is: per-call > per-notion > global. A more specific style always overrides a more general one.

// Global default styles
#synapse-config(
  intro-style: text.with(style: "italic", fill: rgb("#bd4702")),
  syn-style: text.with(weight: "bold", fill: rgb("#3b91d8"))
)

// Per-notion style (overrides global)
#notion("custom", style: text.with(fill: green))

// Per-call style (overrides both global and per-notion)
#intro("custom", style: text.with(fill: red))
#syn("custom", style: text.with(fill: blue))

Note: In “paper” mode, color-related styles (fill and stroke) are automatically removed from global and per-notion styles, but per-call styles are preserved. This allows you to maintain color highlights for specific notions even in print mode.

Rendering mode

Synapse has three rendering modes: “composition”, “electronic” and “paper”. The rendering mode can be set with the synapse-config function and the mode argument. The default rendering mode is “composition”. This is the mode used to build your document. It displays everything like normal but on top of that, it highlights notions with no introductions and notions that haven’t been defined with the notion function. It also displays a red marking with a label to show where the anchors of the notions are. The “electronic” mode displays everything like normal but without the red markings and highlights. The “paper” mode displays everything in black and white. All color-related styles (fill and stroke) are removed, but other styling like font weight and size are preserved.

#synapse-config(mode: "electronic")

This will set the rendering mode to “electronic”. You can change the rendering mode at any point in the document, but it is recommended to set it at the beginning of the document.

Changelog

0.1.2

  • Added a new argument style to the intro and syn functions to allow styling of the links and introductions of the notions. This argument takes a text function as value that will be used to style the links.

0.1.1

  • Fixed a bug where the syn function would pick the wrong context and thus not apply the correct link to the notion.

0.1.0

  • Initial release of the synapse package.