zebraw

Zebraw is a lightweight and fast package for displaying code blocks with line numbers in Typst, supporting code line highlighting. The term zebraw is a combination of zebra and raw, as the highlighted lines display in the code block with a zebra-striped pattern.

Quick Start

Import the zebraw package with #import "@preview/zebraw:0.5.2": * then add #show: zebraw to start using zebraw in the simplest way.

To manually render specific code blocks with zebraw, use the #zebraw() function:

Features

The zebraw function provides a variety of parameters to customize the appearance and behavior of code blocks. The following sections describe these parameters in detail:

• Core Features
  • Customizable line numbering and range slicing
  • Line highlighting and explanatory comments for code
  • Headers and footers
  • Language identifier tabs
  • The indentation guide line and hanging indentation (and fast preview mode for better performance)
• Customization Options
  • Custom colors for background, highlights, and comments
  • Custom fonts for different elements
  • Customizable insets
  • Custom themes
• Export Options
  • Experimental HTML export

Line Numbering

Line numbers appear on the left side of the code block. Change the starting line number by passing an integer to the numbering-offset parameter. The default value is 0.

To disable line numbering, pass false to the numbering parameter:

For more advanced numbering control, pass an array of arrays to the numbering parameter. Each inner array represents a column of markers that will be displayed instead of standard line numbers. This allows displaying multiple line numbers, markers or custom identifiers for each line.

Numbering Separator

You can add a separator line between line numbers and code content by setting the numbering-separator parameter to true:

Line Slicing

Slice code blocks by passing the line-range parameter to the zebraw function. The line-range parameter can be either:

• An array of 2 integers representing the range ( can be none as this feature is based on Typst array slicing)
• A dictionary with range and keep-offset keys

When keep-offset is set to true, line numbers maintain their original values. Otherwise, they reset to start from 1. By default, keep-offset is set to true.

Line Highlighting

Highlight specific lines in the code block by passing the highlight-lines parameter to the zebraw function. The highlight-lines parameter accepts either a single line number or an array of line numbers.

Comments

Add explanatory comments to highlighted lines by passing an array of line numbers and comments to the highlight-lines parameter.

Comments begin with a flag character, which is ">" by default. Change this flag by setting the comment-flag parameter:

To disable the flag feature entirely, pass an empty string "" to the comment-flag parameter (this also disables comment indentation):

Headers and Footers

You can add headers and footers to code blocks. One approach is to use special keys in the highlight-lines parameter:

Alternatively, use the dedicated header and footer parameters for cleaner code:

Language Tab

Display a floating language identifier tab in the top-right corner of the code block by setting lang to true:

Customize the language display by passing a string or content to the lang parameter:

Indentation Lines, Hanging Indentation and Fast Preview

Display indentation guides by passing a positive integer to the indentation parameter, representing the number of spaces per indentation level:

Enable hanging indentation by setting hanging-indent to true:

Indentation lines can slow down preview performance. For faster previews, enable fast preview mode by passing true to the fast-preview parameter in zebraw-init or by using zebraw-fast-preview in the CLI. This renders indentation lines as simple | characters:

Themes

Zebraw includes built-in themes. PRs for additional themes are welcome!

(Experimental) HTML Export

See example-html.typ or GitHub Pages for more information.

Customization

There are three ways to customize code blocks in your document:

1. Per-block customization: Manually style specific blocks using the #zebraw() function with parameters.
2. Local customization: Apply styling to all subsequent raw blocks with #show: zebraw.with(). This affects all raw blocks after the #show rule, except those created manually with #zebraw().
3. Global customization: Use #show: zebraw-init.with() to affect all raw blocks after the rule, including those created manually with #zebraw(). Reset to defaults by using zebraw-init without parameters.

Inset

Customize the padding around each code line(numberings are not affected) by passing a dictionary to the inset parameter:

Colors

Customize the background color with a single color or an array of alternating colors:

Set the highlight color for marked lines with the highlight-color parameter:

Change the comment background color with the comment-color parameter:

Set the language tab background color with the lang-color parameter:

Font

Customize font properties for comments, language tabs, and line numbers by passing a dictionary to the comment-font-args, lang-font-args, or numbering-font-args parameters respectively.

If no custom lang-font-args are provided, language tabs inherit the comment font styling:

Example with custom language tab styling:

Extend

Extend at vertical is enabled at default. When there’s header or footer it will be automatically disabled.

Example

License

Zebraw is licensed under the MIT License. See the LICENSE file for more information.