feat: enhance code block & code group (#2174)

yuyinws · antfu · web-flow · commit 80c8d4248553 · 2025-05-18T16:24:02.000+08:00
Co-authored-by: Anthony Fu &lt;github@antfu.me&gt;
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -2,6 +2,7 @@ import type { DefaultTheme } from 'vitepress'
 import { fileURLToPath } from 'node:url'
 import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { defineConfig } from 'vitepress'
+import { groupIconMdPlugin } from 'vitepress-plugin-group-icons'
 import { version } from '../package.json'
 import Customizations from './customizations'
 import { Advanced, BuiltIn, Guides, Resources } from './pages'
@@ -72,6 +73,9 @@ export default defineConfig({
         },
       }),
     ],
+    config(md) {
+      md.use(groupIconMdPlugin)
+    },
   },
   cleanUrls: true,
   themeConfig: {
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -8,6 +8,7 @@ import './styles/vars.css'
 import './styles/demo.css'
 import './styles/custom.css'
 import 'uno.css'
+import 'virtual:group-icons.css'
 
 export default {
   extends: Theme,
diff --git a/docs/components.d.ts b/docs/components.d.ts
@@ -2,6 +2,7 @@
 // @ts-nocheck
 // Generated by unplugin-vue-components
 // Read more: https://github.com/vuejs/core/pull/3399
+// biome-ignore lint: disable
 export {}
 
 /* prettier-ignore */
@@ -26,6 +27,7 @@ declare module 'vue' {
     CarbonArrowLeft: typeof import('~icons/carbon/arrow-left')['default']
     CarbonArrowRight: typeof import('~icons/carbon/arrow-right')['default']
     CarbonBadge: typeof import('~icons/carbon/badge')['default']
+    CarbonDocumentPdf: typeof import('~icons/carbon/document-pdf')['default']
     CarbonDownload: typeof import('~icons/carbon/download')['default']
     CarbonEdit: typeof import('~icons/carbon/edit')['default']
     CarbonInformation: typeof import('~icons/carbon/information')['default']
@@ -36,6 +38,7 @@ declare module 'vue' {
     CarbonPen: typeof import('~icons/carbon/pen')['default']
     CarbonSettingsAdjust: typeof import('~icons/carbon/settings-adjust')['default']
     CarbonSun: typeof import('~icons/carbon/sun')['default']
+    CarbonTextAnnotationToggle: typeof import('~icons/carbon/text-annotation-toggle')['default']
     CarbonUserAvatar: typeof import('~icons/carbon/user-avatar')['default']
     CarbonUserSpeaker: typeof import('~icons/carbon/user-speaker')['default']
     CarbonVideo: typeof import('~icons/carbon/video')['default']
diff --git a/docs/custom/config-code-runners.md b/docs/custom/config-code-runners.md
@@ -10,7 +10,7 @@ Create `./setup/code-runners.ts` with the following content:
 
 <!-- eslint-disable import/first -->
 
-```ts twoslash
+```ts twoslash [setup/code-runners.ts]
 declare const executePythonCodeRemotely: (code: string) => Promise<string>
 declare const sanitizeHtml: (html: string) => string
 // ---cut---
diff --git a/docs/custom/config-context-menu.md b/docs/custom/config-context-menu.md
@@ -8,7 +8,7 @@ Create `./setup/context-menu.ts` with the following content:
 
 <!-- eslint-disable import/first -->
 
-```ts twoslash
+```ts twoslash [./setup/context-menu.ts]
 // ---cut---
 import { useNav } from '@slidev/client'
 import { defineContextMenuSetup } from '@slidev/types'
diff --git a/docs/custom/config-highlighter.md b/docs/custom/config-highlighter.md
@@ -8,8 +8,7 @@ Slidev uses [Shiki](https://github.com/shikijs/shiki) as the code highlighter. I
 
 Create `./setup/shiki.ts` file with the following content:
 
-```ts twoslash
-/* ./setup/shiki.ts */
+```ts twoslash [setup/shiki.ts]
 import { defineShikiSetup } from '@slidev/types'
 
 export default defineShikiSetup(() => {
@@ -29,8 +28,7 @@ If you want to add custom theme or language (TextMate grammar/themes in JSON), y
 
 <!-- eslint-disable import/first-->
 
-```ts twoslash
-/* ./setup/shiki.ts */
+```ts twoslash [setup/shiki.ts]
 import { defineShikiSetup } from '@slidev/types'
 // ---cut-start---
 // @ts-expect-error missing types
diff --git a/docs/custom/config-katex.md b/docs/custom/config-katex.md
@@ -4,7 +4,7 @@
 
 Create `./setup/katex.ts` with the following content:
 
-```ts twoslash
+```ts twoslash [setup/katex.ts]
 import { defineKatexSetup } from '@slidev/types'
 
 export default defineKatexSetup(() => {
diff --git a/docs/custom/config-mermaid.md b/docs/custom/config-mermaid.md
@@ -4,7 +4,7 @@
 
 Create `./setup/mermaid.ts` with the following content:
 
-```ts twoslash
+```ts twoslash [setup/mermaid.ts]
 import { defineMermaidSetup } from '@slidev/types'
 
 export default defineMermaidSetup(() => {
diff --git a/docs/custom/config-monaco.md b/docs/custom/config-monaco.md
@@ -4,7 +4,7 @@
 
 Create `./setup/monaco.ts` with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/monaco.ts]
 import { defineMonacoSetup } from '@slidev/types'
 
 export default defineMonacoSetup(async (monaco) => {
@@ -71,8 +71,7 @@ console.log('HelloWorld')
 
 Alternatively if you would like these options to be applied to every Monaco instance, you can return them in the `defineMonacoSetup` function
 
-```ts twoslash
-// ./setup/monaco.ts
+```ts twoslash [./setup/monaco.ts]
 import { defineMonacoSetup } from '@slidev/types'
 
 export default defineMonacoSetup(() => {
diff --git a/docs/custom/config-parser.md b/docs/custom/config-parser.md
@@ -26,7 +26,7 @@ The preparser (step 1 above) is highly extensible and allows you to implement cu
 
 To customize it, create a `./setup/preparser.ts` file with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/preparser.ts]
 import { definePreparserSetup } from '@slidev/types'
 
 export default definePreparserSetup(({ filepath, headmatter, mode }) => {
@@ -76,7 +76,7 @@ see you next time
 
 To allow these `@src:` and `@cover:` syntaxes, create a `./setup/preparser.ts` file with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/preparser.ts]
 import { definePreparserSetup } from '@slidev/types'
 
 export default definePreparserSetup(() => {
@@ -157,7 +157,7 @@ Here we used an underscore in `_scale` to avoid possible conflicts with existing
 
 To handle this `_scale: ...` syntax in the frontmatter, create a `./setup/preparser.ts` file with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/preparser.ts]
 import { definePreparserSetup } from '@slidev/types'
 
 export default definePreparserSetup(() => {
@@ -207,7 +207,7 @@ Here we used an underscore in `_note` to avoid possible conflicts with existing
 
 To handle this `_note: ...` syntax in the frontmatter, create a `./setup/preparser.ts` file with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/preparser.ts]
 import fs, { promises as fsp } from 'node:fs'
 import { definePreparserSetup } from '@slidev/types'
 
diff --git a/docs/custom/config-routes.md b/docs/custom/config-routes.md
@@ -8,7 +8,7 @@ Add custom pages to the Slidev app.
 
 Create `./setup/routes.ts` with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/routes.ts]
 import { defineRoutesSetup } from '@slidev/types'
 
 export default defineRoutesSetup((routes) => {
diff --git a/docs/custom/config-shortcuts.md b/docs/custom/config-shortcuts.md
@@ -6,7 +6,7 @@
 
 Create `./setup/shortcuts.ts` with the following content:
 
-```ts twoslash
+```ts twoslash [./setup/shortcuts.ts]
 import type { NavOperations, ShortcutOptions } from '@slidev/types'
 import { defineShortcutsSetup } from '@slidev/types'
 
diff --git a/docs/custom/config-transformers.md b/docs/custom/config-transformers.md
@@ -4,7 +4,7 @@
 
 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
+````ts twoslash [setup/transformers.ts]
 import type { MarkdownTransformContext } from '@slidev/types'
 import { defineTransformersSetup } from '@slidev/types'
 
diff --git a/docs/custom/config-unocss.md b/docs/custom/config-unocss.md
@@ -31,7 +31,7 @@ You can therefore style your content the way you want. For example:
 
 You can create `uno.config.ts` under the root of your project to extend the builtin configurations
 
-```ts twoslash
+```ts twoslash [uno.config.ts]
 import { defineConfig } from 'unocss'
 
 export default defineConfig({
diff --git a/docs/custom/config-vite.md b/docs/custom/config-vite.md
@@ -21,7 +21,7 @@ To configure the built-in plugins listed above, create a `vite.config.ts` with t
 
 <!-- eslint-disable import/first -->
 
-```ts twoslash
+```ts twoslash [vite.config.ts]
 /// <reference types="@slidev/types" />
 import type MarkdownIt from 'markdown-it'
 declare const MyPlugin: (md: any) => void
diff --git a/docs/custom/config-vue.md b/docs/custom/config-vue.md
@@ -8,7 +8,7 @@ Create `./setup/main.ts` with the following content:
 
 <!-- eslint-disable import/first -->
 
-```ts twoslash
+```ts twoslash [setup/main.ts]
 import type { Plugin } from 'vue'
 declare const YourPlugin: Plugin
 // ---cut---
diff --git a/docs/custom/directory-structure.md b/docs/custom/directory-structure.md
@@ -93,8 +93,7 @@ The `index.html` provides the ability to inject meta tags and/or scripts to the
 
 For example, for the following custom `index.html`:
 
-```html
-<!-- ./index.html -->
+```html [index.html]
 <head>
   <link rel="preconnect" href="https://fonts.gstatic.com">
   <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;600&family=Nunito+Sans:wght@200;400;600&display=swap" rel="stylesheet">
diff --git a/docs/guide/global-context.md b/docs/guide/global-context.md
@@ -6,17 +6,13 @@ Slidev injects several global context values for advanced navigation controls.
 
 You can access them directly in your slides or components:
 
-```md
-<!-- slides.md -->
-
+```md [slides.md]
 # Page 1
 
 Current page is: {{ $nav.currentPage }}
 ```
 
-```vue
-<!-- Foo.vue -->
-
+```vue [Foo.vue]
 <template>
   <div>Title: {{ $slidev.configs.title }}</div>
   <button @click="$nav.next">
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -117,7 +117,7 @@ Slidev provides a set of commands in its CLI. Here are some common ones:
 
 To run these commands, you can add them to your `package.json` scripts (which has been done for you if the project was created via `npm init slidev`):
 
-```json
+```json [package.json]
 {
   "scripts": {
     "dev": "slidev --open",
diff --git a/docs/guide/write-addon.md b/docs/guide/write-addon.md
@@ -29,7 +29,7 @@ An addon can also specify its required Slidev version in the same way as themes.
 
 The same as themes, you can preview your addon via a `./slides.md` like this:
 
-```md
+```md [slides.md]
 ---
 addons:
   - ./
diff --git a/docs/guide/write-layout.md b/docs/guide/write-layout.md
@@ -17,8 +17,7 @@ Layouts are Vue components, so you can use all the features of Vue in them.
 
 In the layout component, use `<slot/>` (the default slot) for the slide content:
 
-```vue
-<!-- default.vue -->
+```vue [default.vue]
 <template>
   <div class="slidev-layout default">
     <slot />
@@ -28,8 +27,7 @@ In the layout component, use `<slot/>` (the default slot) for the slide content:
 
 You can also have [named slots](https://vuejs.org/guide/components/slots.html) for more complex layouts:
 
-```vue
-<!-- split.vue -->
+```vue [split.vue]
 <template>
   <div class="slidev-layout split">
     <div class="left">
diff --git a/docs/guide/write-theme.md b/docs/guide/write-theme.md
@@ -48,7 +48,7 @@ Basically, the way to provide global styles, layouts, components and configure t
 
 To provide default Slidev configurations, you can add a `slidev.defaults` field in the `package.json` file, which will be merged with the user's configurations:
 
-```json
+```json [package.json]
 {
   "slidev": {
     "defaults": {
@@ -77,7 +77,7 @@ An error message will be shown when the an incompatible version is used.
 
 By default, Slidev assumes themes support both light mode and dark mode. If you only want your theme to be presented in a specific color schema, you need to specify it explicitly in the `package.json`:
 
-```json
+```json [package.json]
 {
   "slidev": {
     "colorSchema": "light" // or "dark" or "both"
@@ -89,7 +89,7 @@ By default, Slidev assumes themes support both light mode and dark mode. If you
 
 You can preview your theme when developing by using a demo slide deck. To do so, create a `./slides.md` file with the following headmatter:
 
-```md
+```md [slides.md]
 ---
 theme: ./  # Use the theme in the current directory
 ---
diff --git a/docs/package.json b/docs/package.json
@@ -41,6 +41,7 @@
     "unplugin-vue-components": "catalog:prod",
     "vite-plugin-inspect": "catalog:prod",
     "vitepress": "catalog:docs",
+    "vitepress-plugin-group-icons": "catalog:docs",
     "vitepress-plugin-llms": "catalog:docs",
     "vue": "catalog:frontend"
   }
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
@@ -5,6 +5,7 @@ import Icons from 'unplugin-icons/vite'
 import Components from 'unplugin-vue-components/vite'
 import { defineConfig } from 'vite'
 import Inspect from 'vite-plugin-inspect'
+import { groupIconVitePlugin } from 'vitepress-plugin-group-icons'
 import llmstxt from 'vitepress-plugin-llms'
 
 export default defineConfig({
@@ -46,5 +47,6 @@ export default defineConfig({
     }),
     Inspect(),
     UnoCSS(),
+    groupIconVitePlugin(),
   ],
 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
