frame-it

This is the version of the readme adapted for Markdown renderers. This adaption is less than ideal. If you want to copy text and have a faithful render, go to this link.

Introduction

Frame-It offers a straightforward way to define and use custom environments in your documents. Its syntax is designed to integrate seamlessly with your source code.

Two predefined styles are included by default. You can also create custom styling functions that use the same user-facing API while giving you complete control over the Typst elements in your document.

In contrast:

The default styles are merely functions with the correct signature. If they don’t appeal to you, you have complete freedom to define custom styling functions yourself. For reference, this is that signature:

let your-custom-styling-function(title, tags, body, supplement, number, accent-color) = […]

Quick Start

Import and define your desired frames:

#import "@preview/frame-it:2.1.0": *

#let (example, feature, variant) = frames(
  feature: ("Feature",),
  // For each frame kind, you have to provide its supplement title to be displayed
  variant: ("Variant",),
  // You can provide a color or leave it out and it will be generated
  example: ("Example", gray),
)
// This syntax works as well, but colors are not generated automatically
#let syntax = frame("Syntax", green)
// This is necessary. Don't forget this!
#show: frame-style(styles.boxy)

How to use it is explained below. Here is a quick example:

#example[Title][Optional Tag][
  Body, i.e. large content block for the frame.
]

which yields

Feature List

The following features are demonstrated in all predefined styles.

Seamlessly highlight parts of your document

For brief elements, use [] as the body to omit the content.

Highlight parts distinctively

For brief elements, use [] as the body to omit the content.

A third Alternative

We recently added third style, namely styles.thmbox:

For brief elements, use [] as the body to omit the content.

Miscellaneous

Syntax to create single frames

HTML

We were one of the first packages to add support for html!
This means you can use our frames if you’re writing an html wiki or blog in typst.

General

Internally, every frame is just a figure where the kind is set to "frame" (or a different custom value). As such, most things that can be done to a figure can be done with a frame as well. Whenever you would like to do something custom but don’t know if it is supported, try achieving it with a normal figure first and then apply the same show rule to your frames. Here is a list of examples:

For example, you can create an outline which only contains some intentional of your frames like so. The figure function includes a parameter for including a figure in the outline.

// By default, don't include frames in outlines by default
#show figure.where(kind: "frame"): set figure(outlined: false)
// Create the outline
#outline(target: figure.where(kind: "frame"))
// Explicitly include a frame in the outline with the `outlined` parameter.
#example(outlined: true)[Important frame][For the outline]

When you want to change the styling used for a passage of your document, you can just add more show: frame-style() rules:

#show: frame-style(styles.boxy)
#example[In boxy style][]
#show: frame-style(styles.hint)
#example[In hint Style][]

I usually define the abbreviations for the show rule:

// Define once
#let boxy(document) = {show: frame-style(styles.boxy); document}
#let hint(document) = {show: frame-style(styles.hint); document}

// Use it for changing the style used
#show: boxy
#example[In boxy style]
#example[Also in boxy style]
#show: hint
#example[In hint style]

Custom Styling

Internally, there is nothing special about the predefined styles. The only requirement for any styling function is to adhere to the following function signature interface:

where arg is the value passed behind the supplement for each frame variant in the frames function. For the predefined styles, this is the color of the frames. The content returned will be placed as–is in the document.

The older styling.divide() and styling.dividers-as() are deprecated. Use divider() and show divider: ... instead.

frame-it combines very well with [showybox](https://typst.app/universe/package/showybox/) in order to create beautiful styles easily!

Experimental APIs

These APIs are still experimental and subject to change. Use sparingly.

For example, you can use this to color the entries in a outline according to the color of the frame:

#show outline.entry: it => {
  let color = inspect.lookup-frame-info(it.element).color
  text(fill: color.saturate(70%), it)
}
#outline(target: figure.where(kind: "frame"))

Whenever possible, try to discern it using the figures kind instead of this function.

This can be useful, for example, when you want to format references in your document differently. For example, you can do something like this in order to display just title if the referenced element and link to it:

#show ref: it => {
  if inspect.is-frame(it.element) {
    link(it.element.location(), inspect.lookup-frame-info(it.element).title)
  } else {
    it
  }
}

Edge Cases

Here are a few edge cases.

Should be thmbox Other Frame 1 thmbox

A reference to the frame above: Example 47.

 Some Additional Frame 1   Individual : Individual