frame-it

[!NOTE] This is the version of the readme adapted for the Github Readme. 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.

Quick Start

Import and define your desired frames:

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

#let (example, feature, variant, syntax) = 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),
  // You can add as many as you want
  syntax: ("Syntax",),
)
// 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 hightight 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 a third style, namely styles.thmbox:

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

Miscellaneous

HTML

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

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]

Beware that internally, this has to create two distinct figures for technical reason. In general, this approach will be less robust than using the show: frame-style() function.

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 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 going to be 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. When defining your own styling function, it has to have the following signature:

The content returned will be placed as–is in the document.

For more information on how to define your own styling function, please look into the styling module.

Experimentl 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.

Edge Cases

Here are a few edge cases.