Hook Script

The hook script feature is available since tinymisttinymist v0.14.2.

Hook Scripts allow you to hook and customize certain behaviors of tinymist by providing code snippets that will be executed at specific events.

The hook scripts are run as typst scripts with some predefined variables. Since typst is sandboxed, the hook scripts cannot access system directly. However, you can still bind lsp commands to perform complex operations.

The following example demonstrates how to customize the paste behavior when pasting resources into the editing typst document.

• First, the editor client (VS Code) invokes the tinymist.onPastetinymist.onPaste and gets the action to perform. the action contains two fields dirdir, and onConflictonConflict, where dirdir is the directory to store the pasted resources, and onConflictonConflict is the script to execute when a conflict occurs (i.e., the file already exists). Note that importimport statements are allowed in the paste script.
• Then, the editor client checks the physical file system. If it detects conflict when creating a resource file, it again runs the onConflictonConflict script to determine next behavior.
• After several iterations, the editor client finally creates the resource files and inserts the corresponding Typst code into the document.

Specifically, three script hooks will be supported:

• Hook on Paste: customize the paste behavior when pasting resources into the editing typst document.
• Hook on Watch: customize the watch behavior when a file change is detected in the workspaces.
• Hook on Generating Code Actions and Lenses: adding additional code actions by typst scripting.

You could configure tinymist.onPastetinymist.onPaste to customize the paste behavior. It will be executed when pasting resources into the editing typst document. Two kinds of script code are supported:

• If the script code starts with {{ and ends with }}, it will be evaluated as a typst code expression.
• Otherwise, it will be evaluated as a path pattern.

When evaluated as a path pattern, the path variables could be used:

• rootroot: the root of the workspace.
• dirdir: the directory of the current file.
• namename: the name of the current file.

For example, the following path pattern

$root/assets

$root/assets

$root/assets

$root/assets

is evaluated as /path/to/root/assets/path/to/root/assets when pasting main.typmain.typ in /path/to/root/dir/main.typ/path/to/root/dir/main.typ.

When evaluated as a typst code expression, the script could use following predefined definitions:

• rootroot: the root of the workspace.
• dirdir: the directory of the current file.
• namename: the name of the current file.
• joinjoin: a function to join path segments, e.g. join("a", "b", "c")join("a", "b", "c") returns a/b/ca/b/c on Unix-like systems.

For example, the following paste script

{ join(root, "x", dir, if name.ends-with(".png") ("imgs"), name) }

{ join(root, "x", dir, if name.ends-with(".png") ("imgs"), name) }

{ join(root, "x", dir, if name.ends-with(".png") ("imgs"), name) }

{ join(root, "x", dir, if name.ends-with(".png") ("imgs"), name) }

is evaluated as /path/to/root/dir/imgs/main/path/to/root/dir/imgs/main when pasting main.pngmain.png in /path/to/root/dir/main.typ/path/to/root/dir/main.typ.

The result of the paste script could also be a dictionary with the following fields:

• dirdir: the directory to store the pasted resources.

If the result is a string, it will be treated as the dirdir field, i.e. { dir: <result> }{ dir: <result> } and the editor client will creates the pasted resource files in the specified directory.

More fields will be supported in the future. If you have any suggestions, please feel free to open an issue.

Note: this is not implemented yet in current version.

You could configure tinymist.onWatchtinymist.onWatch to customize the watch behavior. It will be executed when a file change is detected in the workspace.

For example, debouncing time:

{ debounce("100ms") }

{ debounce("100ms") }

{ debounce("100ms") }

{ debounce("100ms") }

For example, debounce and

• export by a custom handler and postprocess using ghostscriptghostscript,
• export cover (first page) as SVG.

{ if debounce("1000ms") { (

  ( command: "myExtension.pdfWithGhostScript" ),

  ( export: "svg", pages: "1" ),

) } }

{ if debounce("1000ms") { (

  ( command: "myExtension.pdfWithGhostScript" ),

  ( export: "svg", pages: "1" ),

) } }

{ if debounce("1000ms") { (

  ( command: "myExtension.pdfWithGhostScript" ),

  ( export: "svg", pages: "1" ),

) } }

{ if debounce("1000ms") { (

  ( command: "myExtension.pdfWithGhostScript" ),

  ( export: "svg", pages: "1" ),

) } }

And define a custom command at client side (VS Code):

async function pdfWithGhostScript() {

    const pdfPath = await vscode.commands.execute("tinymist.exportPdf");

    const outputPath = pdfPath.replace(/\.pdf$/, "-gs.pdf");

    return new Promise((resolve, reject) => {

        exec(`gs ... -sOutputFile=${outputPath} ${pdfPath}`, (error, stdout, stderr) => {

            if (error) {

                reject(error);

            } else {

                resolve(outputPath);

            }

        });

    });

}

async function pdfWithGhostScript() {

    const pdfPath = await vscode.commands.execute("tinymist.exportPdf");

    const outputPath = pdfPath.replace(/\.pdf$/, "-gs.pdf");

    return new Promise((resolve, reject) => {

        exec(`gs ... -sOutputFile=${outputPath} ${pdfPath}`, (error, stdout, stderr) => {

            if (error) {

                reject(error);

            } else {

                resolve(outputPath);

            }

        });

    });

}

async function pdfWithGhostScript() {

  const pdfPath = await vscode.commands.execute("tinymist.exportPdf");

  const outputPath = pdfPath.replace(/\.pdf$/, "-gs.pdf");

  return new Promise((resolve, reject) => {

    exec(`gs ... -sOutputFile=${outputPath} ${pdfPath}`, (error, stdout, stderr) => {

      if (error) {

        reject(error);

      } else {

        resolve(outputPath);

      }

    });

  });

}

async function pdfWithGhostScript() {

  const pdfPath = await vscode.commands.execute("tinymist.exportPdf");

  const outputPath = pdfPath.replace(/\.pdf$/, "-gs.pdf");

  return new Promise((resolve, reject) => {

    exec(`gs ... -sOutputFile=${outputPath} ${pdfPath}`, (error, stdout, stderr) => {

      if (error) {

        reject(error);

      } else {

        resolve(outputPath);

      }

    });

  });

}

Hint: you could create your own vscode extension to define such custom commands.

Note: this is not implemented yet in current version.

You could configure tinymist.onCodeActiontinymist.onCodeAction to provide package-specific code actions. It will be executed when requesting code actions in the editing typst document.

For example, matching a table element and providing a code lens to open it in a Microsoft Excel:

{

  code-lens(

    if: ```typc is-func and func.name == "table"```,

    title: "Open in Excel",

    command: "myExtension.openTableInExcel",

    arguments: (sys.inputs，),

  )

}

{

  code-lens(

    if: ```typc is-func and func.name == "table"```,

    title: "Open in Excel",

    command: "myExtension.openTableInExcel",

    arguments: (sys.inputs，),

  )

}

{

  code-lens(

    if: ```typc is-func and func.name == "table"```,

    title: "Open in Excel",

    command: "myExtension.openTableInExcel",

    arguments: (sys.inputs，),

  )

}

{

  code-lens(

    if: ```typc is-func and func.name == "table"```,

    title: "Open in Excel",

    command: "myExtension.openTableInExcel",

    arguments: (sys.inputs，),

  )

}