Skip to content

Dherse/codly

Repository files navigation

Codly: simple and powerful code blocks

Documentation MIT License

Codly is a package that lets you easily create beautiful code blocks for your Typst documents. It uses the newly added raw.line function to work across all languages easily. You can customize the icons, colors, and more to suit your document's theme. By default it has zebra striping, line numbers, for ease of reading.

A full set of documentation can be found in the repo.

Example

#import "@preview/codly:1.0.0": *
#show: codly-init.with()

#codly(
  languages: (
    rust: (
      name: "Rust",
      icon: text(font: "tabler-icons", "\u{fa53}"),
      color: rgb("#CE412B")
    ),
  )
)

```rust
pub fn main() {
    println!("Hello, world!");
}
```

Setup

To start using codly, you need to initialize codly using a show rule:

#show: codly-init.with()

Tip

You only need to do this once at the top of your document!

Then you can configure codly with your parameters:

#codly(
  languages: (
    rust: (name: "Rust", icon: "\u{fa53}", color: rgb("#CE412B")),
  )
)

Important

Any parameter that you leave blank will use the previous values (or the default value if never set) similar to a set rule in regular typst. But the changes are always global unless you use the provided codly.local function. To get a full list of all settings, see the documentation.

Then you just need to add a code block and it will be automatically displayed correctly:

```rust
pub fn main() {
    println!("Hello, world!");
}
```

Disabling

To locally disable codly, you can just do the following, you can then later re-enable it using the codly configuration function.

#disable-codly()

Alternatively, you can use the no-codly function to achieve the same effect locally:

#no-codly[
  ```typ
  I will be displayed using the normal raw blocks.
  ```
]

Setting an offset

If you wish to add an offset to your code block, but without selecting a subset of lines, you can use the codly-offset function:

// Sets a 5 line offset
#codly-offset(5)

Selecting a subset of lines

If you wish to select a subset of lines, you can use the codly-range function. By setting the start to 1 and the end to none you can select all lines from the start to the end of the code block.

#codly-range(start: 5, end: 10)

Adding a "skip"

You can add a "fake" skip between lines using the skips parameters:

// Before the 5th line (indexing start at 0), insert a 32 line jump.
#codly(skips: ((4, 32), ))

The code inside your block will be the same (except for the added line containing the … character), but the line numbers will be adjusted to reflect the skip.

This can be customized using the skip-line and skip-number to customize what it looks like.

Adding annotations

Important

This is a Beta feature and has a few quirks, refer to the documentation for those

You can annotate a line/group of lines using the annotations parameters :

// Add an annotation from the second line (0 indexing) to the 5th line included.
#codly(
  annotations: (
    (
      start: 1,
      end: 4,
      content: block(
        width: 2em,
        // Rotate the element to make it look nice
        rotate(
          -90deg,
          align(center, box(width: 100pt)[Function body])
        )
      )
    ), 
  )
)

Disabling line numbers

You can configure this with the codly function:

#codly(number-format: none)

Disabling zebra striping

You disable zebra striping by setting the zebra-fill to white or none.

#codly(zebra-fill: none)

Customize the stroke

You can customize the stroke surrounding the figure using the stroke parameter of the codly function:

#codly(stroke: 1pt + red)

Misc

You can also disable the icon by setting the display-icon parameter to false:

#codly(display-icon: false)

This applies to:

  • the name
  • the radius
  • whether the block is breakable
  • the padding
  • the width of the numbers columns

and so many more.

For more detailed information check out the documentation.