Transformers

Shiki uses hast, an AST format for HTML, to process the result and generate the HTML.

You can provide your own transformers to customize the generated HTML by manipulating the HAST tree. Pass custom functions to modify the tree for different node types. For example:

import { codeToHtml } from 'shiki';

const code = await codeToHtml('foo\\bbar', {
  lang: 'js',
  theme: 'vitesse-light',
  transformers: [
    {
      code(node) {
        this.addClassToHast(node, 'language-js');
      },
      line(node) {
        this.addClassToHast(node, 'highlight');
      },
      span(node) {
        // Example: add a data-token attribute to each span.
        node.properties['data-token'] = `token:${node.properties.line}:${node.properties.col}`;
      }
    }
  ]
});

We also provide some common transformers for you to use—see @shikijs/transformers and @shikijs/colorized-brackets for more details.

Transformer Hooks

• preprocess – Called before the code is tokenized. You can modify the code before it is tokenized.
• tokens – Called after the code is tokenized. You can modify the tokens.
• span – Called for each <span> tag, for each token.
• line – Called for each line <span> tag.
• code – Called for each <code> tag, wraps all the lines.
• pre – Called for each <pre> tag, wraps the <code> tag.
• root – The root of the HAST tree. Usually contains a single <pre> child.
• postprocess – Called after the HTML is generated, giving a chance to modify the final output. Not called in codeToHast.

Meta

Transformers can also access markdown meta strings in supported integrations.

```html foo=bar baz-qux="qu ux"

You can access the raw meta using:

this.options.meta
// => { __raw: 'foo=bar baz-qux="qu ux"' }

Enforcing Transformer Ordering

For compatibility or fine‑grained control, it may be necessary to enforce the order of a Shiki transformer. Control the position of a transformer with the enforce modifier:

• pre – invoked before normal transformers
• default – invoked as a normal transformer
• post – invoked after normal transformers

Example:

import type { ShikiTransformer } from 'shiki';

const customTransformer: ShikiTransformer = {
  name: 'my-transformer',
  enforce: 'pre',
  code(node) {
    // ...
  }
};

Previous page: Decorations
Next page: Theme Colors Manipulation