feat(core): add enforce options to ShikiTransformer (#1062)

Co-authored-by: Anthony Fu <[email protected]>

Author: serkodev

docs/guide/transformers.md

@@ -73,3 +73,25 @@ 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. You can control the position of a transformer with the `enforce` modifier:
+
+- `pre`: invoked before normal transformers
+- default: invoked as a normal transformers
+- `post`: invoked after normal transformers
+
+Example:
+
+```ts twoslash
+import type { ShikiTransformer } from 'shiki'
+
+const customTransformer: ShikiTransformer = {
+  name: 'my-transformer',
+  enforce: 'pre',
+  code(node) {
+    // ...
+  },
+}
+```

packages/core/src/highlight/_get-transformers.ts

@@ -6,8 +6,36 @@ const builtInTransformers: ShikiTransformer[] = [
 ]
 
 export function getTransformers(options: TransformerOptions): ShikiTransformer[] {
+  const transformers = sortTransformersByEnforcement(options.transformers || [])
   return [
-    ...options.transformers || [],
+    ...transformers.pre,
+    ...transformers.normal,
+    ...transformers.post,
     ...builtInTransformers,
   ]
 }
+
+function sortTransformersByEnforcement(transformers: ShikiTransformer[]): {
+  pre: ShikiTransformer[]
+  post: ShikiTransformer[]
+  normal: ShikiTransformer[]
+} {
+  const pre: ShikiTransformer[] = []
+  const post: ShikiTransformer[] = []
+  const normal: ShikiTransformer[] = []
+
+  for (const transformer of transformers) {
+    switch (transformer.enforce) {
+      case 'pre':
+        pre.push(transformer)
+        break
+      case 'post':
+        post.push(transformer)
+        break
+      default:
+        normal.push(transformer)
+    }
+  }
+
+  return { pre, post, normal }
+}

packages/types/src/transformers.ts

@@ -50,6 +50,17 @@ export interface ShikiTransformer {
    * Name of the transformer
    */
   name?: string
+  /**
+   * Enforce plugin invocation tier similar to webpack loaders. Hooks ordering
+   * is still subject to the `order` property in the hook object.
+   *
+   * Plugin invocation order:
+   * - `enforce: 'pre'` plugins
+   * - normal plugins
+   * - `enforce: 'post'` plugins
+   * - shiki post plugins
+   */
+  enforce?: 'pre' | 'post'
   /**
    * Transform the raw input code before passing to the highlighter.
    */