feat: allow to customize markdown transformers (#1767)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: kermanx

docs/.vitepress/customizations.ts

@@ -27,6 +27,10 @@ export default [
     text: 'Configure Code Runners',
     link: '/custom/config-code-runners',
   },
+  {
+    text: 'Configure Transformers',
+    link: '/custom/config-transformers',
+  },
   {
     text: 'Configure Monaco',
     link: '/custom/config-monaco',

docs/custom/config-transformers.md

@@ -0,0 +1,43 @@
+# Configure Transformers
+
+<Environment type="node" />
+
+This setup function allows you to define custom transformers for the markdown content of **each slide**. This is useful when you want to add custom Markdown syntax and render custom code blocks. To start, create a `./setup/transformers.ts` file with the following content:
+
+````ts twoslash
+import type { MarkdownTransformContext } from '@slidev/types'
+import { defineTransformersSetup } from '@slidev/types'
+
+function myCodeblock(ctx: MarkdownTransformContext) {
+  console.log('index in presentation', ctx.slide.index)
+  ctx.s.replace(
+    /^```myblock *(\{[^\n]*\})?\n([\s\S]+?)\n```/gm,
+    (full, options = '', code = '') => {
+      return `...`
+    },
+  )
+}
+
+export default defineTransformersSetup(() => {
+  return {
+    pre: [],
+    preCodeblock: [myCodeblock],
+    postCodeblock: [],
+    post: [],
+  }
+})
+````
+
+The return value should be the custom options for the transformers. The `pre`, `preCodeblock`, `postCodeblock`, and `post` are arrays of functions that will be called in order to transform the markdown content. The order of the transformers is:
+
+1. `pre` from your project
+2. `pre` from addons and themes
+3. Import snippets syntax and Shiki magic move
+4. `preCodeblock` from your project
+5. `preCodeblock` from addons and themes
+6. Built-in special code blocks like Mermaid, Monaco and PlantUML
+7. `postCodeblock` from addons and themes
+8. `postCodeblock` from your project
+9. Other built-in transformers like code block wrapping
+10. `post` from addons and themes
+11. `post` from your project

packages/slidev/node/setups/transformers.ts

@@ -0,0 +1,25 @@
+import type { TransformersSetup, TransformersSetupReturn } from '@slidev/types'
+import { loadSetups } from './load'
+
+export default async function setupTransformers(roots: string[]) {
+  const returns = await loadSetups<TransformersSetup>(roots, 'transformers.ts', [])
+  const result: TransformersSetupReturn = {
+    pre: [],
+    preCodeblock: [],
+    postCodeblock: [],
+    post: [],
+  }
+  for (const r of returns.toReversed()) {
+    if (r.pre)
+      result.pre.push(...r.pre)
+    if (r.preCodeblock)
+      result.preCodeblock.push(...r.preCodeblock)
+  }
+  for (const r of returns) {
+    if (r.postCodeblock)
+      result.postCodeblock.push(...r.postCodeblock)
+    if (r.post)
+      result.post.push(...r.post)
+  }
+  return result
+}

packages/slidev/node/syntax/transform/in-page-css.ts

@@ -5,10 +5,6 @@ import { getCodeBlocks } from './utils'
  * Transform <style> in markdown to scoped style with page selector
  */
 export function transformPageCSS(ctx: MarkdownTransformContext) {
-  const page = ctx.id.match(/(\d+)\.md$/)?.[1]
-  if (!page)
-    return
-
   const codeBlocks = getCodeBlocks(ctx.s.original)
 
   ctx.s.replace(

packages/slidev/node/syntax/transform/index.ts

@@ -1,4 +1,5 @@
-import type { MarkdownTransformContext, MarkdownTransformer } from '@slidev/types'
+import type { MarkdownTransformer, ResolvedSlidevOptions } from '@slidev/types'
+import setupTransformers from '../../setups/transformers'
 import { transformCodeWrapper } from './code-wrapper'
 import { transformPageCSS } from './in-page-css'
 import { transformKaTexWrapper } from './katex-wrapper'
@@ -9,27 +10,27 @@ import { transformPlantUml } from './plant-uml'
 import { transformSlotSugar } from './slot-sugar'
 import { transformSnippet } from './snippet'
 
-export function applyMarkdownTransform(ctx: MarkdownTransformContext) {
-  const transformers: (MarkdownTransformer | false)[] = [
+export async function getMarkdownTransformers(options: ResolvedSlidevOptions): Promise<(false | MarkdownTransformer)[]> {
+  const extras = await setupTransformers(options.roots)
+  return [
+    ...extras.pre,
+
     transformSnippet,
-    ctx.options.data.config.highlighter === 'shiki'
-    && transformMagicMove,
+    options.data.config.highlighter === 'shiki' && transformMagicMove,
+
+    ...extras.preCodeblock,
+
     transformMermaid,
     transformPlantUml,
-    ctx.options.data.features.monaco
-    && transformMonaco,
+    options.data.features.monaco && transformMonaco,
+
+    ...extras.postCodeblock,
+
     transformCodeWrapper,
-    ctx.options.data.features.katex
-    && transformKaTexWrapper,
+    options.data.features.katex && transformKaTexWrapper,
     transformPageCSS,
     transformSlotSugar,
-  ]
 
-  for (const transformer of transformers) {
-    if (!transformer)
-      continue
-    transformer(ctx)
-    if (!ctx.s.isEmpty())
-      ctx.s.commit()
-  }
+    ...extras.post,
+  ]
 }

packages/slidev/node/syntax/transform/snippet.ts

@@ -83,17 +83,11 @@ function findRegion(lines: Array<string>, regionName: string) {
  *
  * captures: ['/path/to/file.extension', '#region', 'language', '{meta}']
  */
-export function transformSnippet(ctx: MarkdownTransformContext) {
-  const options = ctx.options
-  const slideId = (ctx.id as string).match(/(\d+)\.md$/)?.[1]
-  if (!slideId)
-    return
-
+export function transformSnippet({ s, slide, options }: MarkdownTransformContext) {
   const data = options.data
-  const slideInfo = data.slides[+slideId - 1]
-  const dir = path.dirname(slideInfo.source?.filepath ?? options.entry ?? options.userRoot)
+  const dir = path.dirname(slide.source?.filepath ?? options.entry ?? options.userRoot)
 
-  ctx.s.replace(
+  s.replace(
     // eslint-disable-next-line regexp/no-super-linear-backtracking
     /^<<<\s*(\S.*?)(#[\w-]+)?\s*(?:\s(\S+?))?\s*(\{.*)?$/gm,
     (full, filepath = '', regionName = '', lang = '', meta = '') => {
@@ -114,8 +108,8 @@ export function transformSnippet(ctx: MarkdownTransformContext) {
 
       let content = fs.readFileSync(src, 'utf8')
 
-      slideInfo.snippetsUsed ??= {}
-      slideInfo.snippetsUsed[src] = content
+      slide.snippetsUsed ??= {}
+      slide.snippetsUsed[src] = content
 
       if (regionName) {
         const lines = content.split(/\r?\n/)

packages/slidev/node/vite/hmrPatch.ts

@@ -10,9 +10,7 @@ export function createHmrPatchPlugin(): Plugin {
     transform(code, id) {
       if (!id.match(regexSlideSourceId))
         return
-      const replaced = code.replace('if (_rerender_only)', 'if (false)')
-      if (replaced !== code)
-        return replaced
+      return code.replace('if (_rerender_only)', 'if (false)')
     },
   }
 }

packages/slidev/node/vite/markdown.ts

@@ -2,14 +2,16 @@ import Markdown from 'unplugin-vue-markdown/vite'
 import type { Plugin } from 'vite'
 import type { MarkdownTransformContext, ResolvedSlidevOptions, SlidevPluginOptions } from '@slidev/types'
 import MagicString from 'magic-string-stack'
-import { applyMarkdownTransform } from '../syntax/transform'
+import { getMarkdownTransformers } from '../syntax/transform'
 import { useMarkdownItPlugins } from '../syntax/markdown-it'
+import { regexSlideSourceId } from './common'
 
 export async function createMarkdownPlugin(
   options: ResolvedSlidevOptions,
   { markdown: mdOptions }: SlidevPluginOptions,
 ): Promise<Plugin> {
   const markdownTransformMap = new Map<string, MagicString>()
+  const transformers = await getMarkdownTransformers(options)
 
   return Markdown({
     include: [/\.md$/],
@@ -32,20 +34,29 @@ export async function createMarkdownPlugin(
     transforms: {
       ...mdOptions?.transforms,
       before(code, id) {
-        if (id === options.entry)
-          return ''
+        code = mdOptions?.transforms?.before?.(code, id) ?? code
 
+        const match = id.match(regexSlideSourceId)
+        if (!match)
+          return code
+
+        const s = new MagicString(code)
+        markdownTransformMap.set(id, s)
         const ctx: MarkdownTransformContext = {
-          s: new MagicString(code),
-          id,
+          s,
+          slide: options.data.slides[+match[1] - 1],
           options,
         }
 
-        applyMarkdownTransform(ctx)
-        markdownTransformMap.set(id, ctx.s)
+        for (const transformer of transformers) {
+          if (!transformer)
+            continue
+          transformer(ctx)
+          if (!ctx.s.isEmpty())
+            ctx.s.commit()
+        }
 
-        const s = ctx.s.toString()
-        return mdOptions?.transforms?.before?.(s, id) ?? s
+        return s.toString()
       },
     },
   }) as Plugin

packages/types/src/setups.ts

@@ -9,6 +9,7 @@ import type { MermaidConfig } from 'mermaid'
 import type { SlidevPreparserExtension } from './types'
 import type { CodeRunnerProviders } from './code-runner'
 import type { ContextMenuItem } from './context-menu'
+import type { MarkdownTransformer } from './transform'
 
 export interface AppContext {
   app: App
@@ -61,10 +62,18 @@ export type ShikiSetupReturn =
     }
   >
 
+export interface TransformersSetupReturn {
+  pre: (MarkdownTransformer | false)[]
+  preCodeblock: (MarkdownTransformer | false)[]
+  postCodeblock: (MarkdownTransformer | false)[]
+  post: (MarkdownTransformer | false)[]
+}
+
 // node side
 export type ShikiSetup = (shiki: ShikiContext) => Awaitable<ShikiSetupReturn | void>
 export type KatexSetup = () => Awaitable<Partial<KatexOptions> | void>
 export type UnoSetup = () => Awaitable<Partial<UnoCssConfig> | void>
+export type TransformersSetup = () => Awaitable<Partial<TransformersSetupReturn>>
 export type PreparserSetup = (context: {
   filepath: string
   headmatter: Record<string, unknown>
@@ -94,6 +103,7 @@ export const defineRoutesSetup = defineSetup<RoutesSetup>
 export const defineMermaidSetup = defineSetup<MermaidSetup>
 export const defineKatexSetup = defineSetup<KatexSetup>
 export const defineShortcutsSetup = defineSetup<ShortcutsSetup>
+export const defineTransformersSetup = defineSetup<TransformersSetup>
 export const definePreparserSetup = defineSetup<PreparserSetup>
 export const defineCodeRunnersSetup = defineSetup<CodeRunnersSetup>
 export const defineContextMenuSetup = defineSetup<ContextMenuSetup>

packages/types/src/transform.ts

@@ -1,9 +1,21 @@
 import type MagicString from 'magic-string-stack'
 import type { ResolvedSlidevOptions } from './options'
+import type { SlideInfo } from './types'
 
 export interface MarkdownTransformContext {
+  /**
+   * The magic string instance for the current markdown content
+   */
   s: MagicString
-  id: string
+
+  /**
+   * The slide info of the current slide
+   */
+  slide: SlideInfo
+
+  /**
+   * Resolved Slidev options
+   */
   options: ResolvedSlidevOptions
 }
 

test/_tutils.ts

@@ -6,7 +6,7 @@ export function createTransformContext(code: string, shiki?: any): MarkdownTrans
   const s = new MagicString(code)
   return {
     s,
-    id: '1.md',
+    slide: { } as any,
     options: {
       userRoot: path.join(__dirname, './fixtures/'),
       data: {

test/transform-all.test.ts

@@ -1,5 +1,5 @@
 import { expect, it } from 'vitest'
-import { applyMarkdownTransform } from '../packages/slidev/node/syntax/transform'
+import { getMarkdownTransformers } from '../packages/slidev/node/syntax/transform'
 import { createTransformContext } from './_tutils'
 
 it('transform-all', async () => {
@@ -30,7 +30,26 @@ Foo \`{{ code }}\`
 <<< ./fixtures/snippets/snippet.ts#snippet
 `)
 
-  applyMarkdownTransform(ctx)
+  const transformers = await getMarkdownTransformers({
+    roots: [],
+    data: {
+      config: {
+        highlighter: 'shiki',
+      },
+      features: {
+        monaco: true,
+        katex: true,
+      },
+    },
+  } as any)
+
+  for (const transformer of transformers) {
+    if (!transformer)
+      continue
+    transformer(ctx)
+    if (!ctx.s.isEmpty())
+      ctx.s.commit()
+  }
 
   expect(ctx.s.toString()).toMatchSnapshot()
 })