For a template I am developing, I need to both define formatting rules for built-in Typst element functions and write custom (pseudo-element) functions, like an extension of Typst’s figure that allows me to add a note between figure content and caption. My goal is to set this up such that I can define formatting rules in one central place where they are easy to track, and keep additional function definitions separate from that in a modular way. But I am unsure how I can achieve this in Typst.
The first best would be to define my own pseudo-element functions as proper element functions and make some of their arguments settable. But Typst does not seem to allow that, or does it?
The second best would be to define options for my own pseudo-element functions as ‘global constants’ within my main template function. But I don’t think there is a way to access variable definitions inside the template function from outside functions?
This is a more generic question, so I appreciate any kind of insights, opinions or pointers to other resources or debates elsewhere. To make my issue a bit clearer, I have added a simple working example below.
Cheers,
Joscha
Example:
#let template(body) = {
// this is where I would ideally like to keep all my style definitions
// in one place
show figure: set text(fill: red)
body
}
// this is the function definition, which I would like to keep as generic
// as possible for it to work well with many different potential templates
// without needing to be re-written
#let my-figure(content, note: [], ..args) = {
figure(..args)[
#content
#if note != [] {
block()[
// here is where I have to define the style of my figure note
// -> ideally, I would define this in my central template function
// and only specify defaults here
#set text(fill: green)
Note: #note
]
}
]
}
#show: template
#lorem(80)
#my-figure(
rect(width: 80%, height: 20%),
note: [#lorem(30)],
caption: [#lorem(10)]
)
#lorem(80)
For your specific case of a figure with an optional and configurable note I would do the following:
#let template(body) = {
// you can set up your default/recommended rules here
show figure.caption: set text(fill: red)
body
}
// you can set up the default style for your notes here
#let my-note(fill: green, supplement: "Note", body) = block[
#set text(fill: fill)
#supplement: #body
]
// this function is kept very general, "note" can either be none or content
#let my-figure(content, note: none, ..args) = {
figure(..args)[
#content
#if note != none { note }
]
}
#show: template
// you can override the rules from the template here if you don't like the default style
// (this might not work for complex show rules that completely modify an element)
#show figure.caption: set text(fill: purple)
// you can override the style of the figure notes by redefining the default values
#let my-note = my-note.with(fill: blue)
#my-figure(
rect(width: 80%, height: 20%),
note: my-note(lorem(30)),
caption: [#lorem(10)]
)
While this requires you to pass the note content through the function figure-note(), I wouldn’t mind the additional “verbosity” for the gain in the flexibility.
If you haven’t seen it yet, this post is definitely worth reading if you want some more insights into writing and using templates. Don’t get too excited though, you won’t be able to directly apply everything you see there to your template. Some of the answers already look ahead what templates can/would look like when custom types are available.
As a rule, I think it’s best to stick to native elements functions and extend them with additional functions. Unless you really need it (eg for theorems, etc.), I don’t see the benefit of defining a custom figure function. Not only will it confuse the users of your template, but also just add unnecessary complexity to your template. I believe most styling can be achieved with show rules.
As an example, here is how I defined figure notes for an INFORMS journal template.
#let figure-note(body) = (
context {
let kind = {
query(selector(figure).before(here())).last().kind
}
set par(first-line-indent: 0pt)
set text(scriptsize)
if kind == table {
align(
center,
{
[Table Notes.]
h(.5em)
body
},
)
} else {
{
[_Note._]
h(.5em)
body
}
}
}
)
@janekfleper Thanks for the inspiration and the link - really interesting discussion, makes me hope that custom types will be implemented sooner rather than later.
@quachpas I totally agree with you with respect to using native elements wherever possible, and thanks for sharing your approach. In this particular case, I do not see a straightforward way to implement my desired behaviour without a custom function, though. After all, I want the figure note to appear ‘within’ the figure; or at least to float with it in case I choose floating placement. Happy to be proven wrong though!
I prefer to define show/set rules as functions, and pass them at the templating stage to make things less of a clutter
In a template, you control everything, so as long as you embed enough metadata you can entirely control the layout without affecting the user functions such as figures, etc. What you were missing was the usage of queries.
Note styling is in the note function (green text)
Figure styling is in the style-figure function (red text)
An additional prefix is added for the metadata in order to differentiate it from other metadata which could be embedded in the document.
// All styling show/set rules
#let note(note) = { // Formatting of the note
set text(fill: green)
note
}
#let style-figure = it => context { // show figure rule
// Styling
set text(red)
// Retrieve figure note
let q = query(
selector(metadata) // Find the note between
.after(here()) // current figure and
.before(selector(figure).after(here())) // next figure, if it exists
)
q = q.filter(x => x.value.starts-with("fignote:"))
let note-text = if q.len() > 0 {
q.first().value.slice(8)
} else {
""
}
// Layout Figure
it.body
if note-text != "" { note(note-text) }
it.caption
}
#let figure-note(note) = { // User interface to note a figure
metadata("fignote:" + note)
}
#let template(body) = { // Template function for the _layout_
// Styling
show figure: style-figure
// Layout
body
}
#show: template
#lorem(80)
#figure(
rect(width: 80%, height: 20%),
caption: [#lorem(6)]
)
#figure-note(lorem(6))
#figure(
rect(width: 80%, height: 20%),
caption: [#lorem(7)]
)
#figure(
rect(width: 80%, height: 20%),
caption: [#lorem(8)]
)
#figure-note(lorem(8))
// Incorrect usage of a figure note, nothing should happen
#figure-note(lorem(1))
#figure(
rect(width: 80%, height: 20%),
caption: [#lorem(9)]
)
#metadata("random metadata which should not appear")
#figure-note(lorem(9))
#lorem(80)
@quachpas Thanks a lot for this detailed example! I had gotten to the point where I suspected querying might be the way to go but had failed to make it work because I did not know I could use #metadata in this way.
I’ve marked this as a solution since it solves my immediate issue and may be a blueprint for similar cases. But will stay tuned for the discussion about custom types and ways to make templates more generic and easier to ‘tweak’.
This is maybe a meta question, how do I as a typst user know that {it.body; it.caption} is an acceptable figure show function (that it does the default thing?) and how does it interact with other templates, it could possibly conflict with other styling, right?
Typst does not prevent users from overwriting default layout behaviours of any elements, so there is no “acceptability criteria”. You can write show figure: it => {}, and typst couldn’t care less.
As for the default layout, you don’t know that it is the default. I would actually argue that since you have overwritten, it’s already not the “default” behaviour. It just looks like it.
It interacts very badly! At the moment, there is no way to know whether existing rules are registered for an element.
There is a limited way to combine styling if you return the element itself (it), eg
show figure: it => {
if it.kind == table {
// stuff
} else {
it
}
}
is potentially compatible with additional styling because it would end up in the else clause.
