docs: update code runner docs (#1393)

slidevjs · Mar 8, 2024 · ed61a3a · ed61a3a
1 parent a7918eb
commit ed61a3a
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 0 deletions.
diff --git a/docs/custom/config-code-runners.md b/docs/custom/config-code-runners.md
@@ -29,3 +29,28 @@ export default defineCodeRunnersSetup(() => {
   }
 })
 ```
+
+## Runner Context
+
+The second argument `ctx` is the runner context, which contains the following properties:
+
+```ts
+export interface CodeRunnerContext {
+  /**
+   * Options passed to runner via the `runnerOptions` prop.
+   */
+  options: Record<string, unknown>
+  /**
+   * Highlight code with shiki.
+   */
+  highlight: (code: string, lang: string, options?: Partial<CodeToHastOptions>) => Promise<string>
+  /**
+   * Use (other) code runner to run code.
+   */
+  run: (code: string, lang: string) => Promise<CodeRunnerOutputs>
+}
+```
+
+## Runner Output
+
+The runner can either return a text or HTML output, or an element to be mounted. Refer to https://github.com/slidevjs/slidev/blob/main/packages/types/src/code-runner.ts for more details.
diff --git a/packages/types/src/code-runner.ts b/packages/types/src/code-runner.ts
@@ -2,8 +2,17 @@ import type { CodeToHastOptions } from 'shiki'
 import type { Arrayable, Awaitable } from '@antfu/utils'
 
 export interface CodeRunnerContext {
+  /**
+   * Options passed to runner via the `runnerOptions` prop.
+   */
   options: Record<string, unknown>
+  /**
+   * Highlight code with shiki.
+   */
   highlight: (code: string, lang: string, options?: Partial<CodeToHastOptions>) => Promise<string>
+  /**
+   * Use (other) code runner to run code.
+   */
   run: (code: string, lang: string) => Promise<CodeRunnerOutputs>
 }