Formatting Features

Typstyle follows a consistent set of formatting rules to ensure your Typst code is readable, maintainable, and follows established conventions. This page documents the core formatting styles applied by typstyle.

ℹNote

All examples are automatically rendered using the embedded typstyle formatter, ensuring they always reflect the latest features.

However, documentation updates may lag behind new features. If there are inconsistencies between descriptions and example output, the actual formatting behavior takes precedence.

Configuration

Line Width and Indentation

Default line width: 80 characters (configurable with --line-width--line-width)
Default indentation: 2 spaces per level (configurable with --indent-width--indent-width)
File endings: typstyle ensures files end with a newline character

Comments

Inline Comments

Inline comments are preserved and positioned correctly:

Before

1
#let conf(   title: none,//comments
2
authors: (),
3
  abstract: [],
4
    lang:     "zh",// language
5
  doctype: "book",//comments
6
7
doc,// my docs
8
) = { doc
9
}
10
11
#{
12
  let c = 0// my comment
13
}

1
#let conf(   title: none,//comments
2
authors: (),
3
  abstract: [],
4
    lang:     "zh",// language
5
  doctype: "book",//comments
6
7
doc,// my docs
8
) = { doc
9
}
10
11
#{
12
  let c = 0// my comment
13
}

After

1
#let conf(
2
  title: none, //comments
3
  authors: (),
4
  abstract: [],
5
  lang: "zh", // language
6
  doctype: "book", //comments
7
8
  doc, // my docs
9
) = { doc }
10
11
#{
12
  let c = 0 // my comment
13
}
14

1
#let conf(
2
  title: none, //comments
3
  authors: (),
4
  abstract: [],
5
  lang: "zh", // language
6
  doctype: "book", //comments
7
8
  doc, // my docs
9
) = { doc }
10
11
#{
12
  let c = 0 // my comment
13
}
14

Block Comments

Block comments are automatically aligned and formatted:

Before

1
#{
2
  let x = 1   /* Attached block comment
3
      that spans
4
 multiple lines
5
  */
6
7
  /* Block comment
8
      that spans
9
 multiple lines
10
  */
11
}
12
13
Aligned: /* Block comment with leading stars
14
    *  that
15
        *  spans
16
 *  multiple
17
    *  lines
18
  */

1
#{
2
  let x = 1   /* Attached block comment
3
      that spans
4
 multiple lines
5
  */
6
7
  /* Block comment
8
      that spans
9
 multiple lines
10
  */
11
}
12
13
Aligned: /* Block comment with leading stars
14
    *  that
15
        *  spans
16
 *  multiple
17
    *  lines
18
  */

After

1
#{
2
  let x = 1 /* Attached block comment
3
                 that spans
4
            multiple lines
5
             */
6
7
  /* Block comment
8
       that spans
9
  multiple lines
10
   */
11
}
12
13
Aligned: /* Block comment with leading stars
14
          *  that
15
          *  spans
16
          *  multiple
17
          *  lines
18
          */
19

1
#{
2
  let x = 1 /* Attached block comment
3
                 that spans
4
            multiple lines
5
             */
6
7
  /* Block comment
8
       that spans
9
  multiple lines
10
   */
11
}
12
13
Aligned: /* Block comment with leading stars
14
          *  that
15
          *  spans
16
          *  multiple
17
          *  lines
18
          */
19

Disabling Formatting

Use // @typstyle off// @typstyle off to disable formatting for specific code regions:

Before

1
// @typstyle off
2
#let intentionally_bad_format    =    "preserved";
3
#let properly_formatted="cleaned up"

1
// @typstyle off
2
#let intentionally_bad_format    =    "preserved";
3
#let properly_formatted="cleaned up"

After

1
// @typstyle off
2
#let intentionally_bad_format    =    "preserved";
3
#let properly_formatted = "cleaned up"
4

1
// @typstyle off
2
#let intentionally_bad_format    =    "preserved";
3
#let properly_formatted = "cleaned up"
4

ℹNote

The escape hatch only applies to the next syntax node, not the rest of the code.

There is no closing // @typstyle on// @typstyle on directive.

For details, please see Escape Hatch.