@slidev/docs 51.6.2

package/custom/config-parser.md

@@ -0,0 +1,232 @@
+# Configure Pre-Parser
+
+::: info
+Custom pre-parsers are not supposed to be used too often. Usually you can use [Transformers](./config-transformers) for custom syntaxes.
+:::
+
+Slidev parses your presentation file (e.g. `slides.md`) in three steps:
+
+1. A "preparsing" step is carried out: the file is split into slides using the `---` separator, and considering the possible frontmatter blocks.
+2. Each slide is parsed with an external library.
+3. Slidev resolves the special frontmatter property `src: ....`, which allows to include other md files.
+
+## Markdown Parser
+
+Configuring the markdown parser used in step 2 can be done by [configuring Vite internal plugins](/custom/config-vite#configure-internal-plugins).
+
+## Preparser Extensions
+
+> Available since v0.37.0.
+
+::: warning
+Important: when modifying the preparser configuration, you need to stop and start Slidev again (restart might not be sufficient).
+:::
+
+The preparser (step 1 above) is highly extensible and allows you to implement custom syntaxes for your md files. Extending the preparser is considered **an advanced feature** and is susceptible to breaking [editor integrations](../features/side-editor) due to implicit changes in the syntax.
+
+To customize it, create a `./setup/preparser.ts` file with the following content:
+
+```ts twoslash
+import { definePreparserSetup } from '@slidev/types'
+
+export default definePreparserSetup(({ filepath, headmatter, mode }) => {
+  return [
+    {
+      transformRawLines(lines) {
+        for (const i in lines) {
+          if (lines[i] === '@@@')
+            lines[i] = 'HELLO'
+        }
+      },
+    }
+  ]
+})
+```
+
+This example systematically replaces any `@@@` line with a line with `hello`. It illustrates the structure of a preparser configuration file and some of the main concepts the preparser involves:
+
+- `definePreparserSetup` must be called with a function as parameter.
+- The function receives the file path (of the root presentation file), the headmatter (from the md file) and, since v0.48.0, a mode (dev, build or export). It could use this information (e.g., enable extensions based on the presentation file or whether we are exporting a PDF).
+- The function must return a list of preparser extensions.
+- An extension can contain:
+  - a `transformRawLines(lines)` function that runs just after parsing the headmatter of the md file and receives a list of all lines (from the md file). The function can mutate the list arbitrarily.
+  - a `transformSlide(content, frontmatter)` function that is called for each slide, just after splitting the file, and receives the slide content as a string and the frontmatter of the slide as an object. The function can mutate the frontmatter and must return the content string (possibly modified, possibly `undefined` if no modifications have been done).
+  - a `transformNote(note, frontmatter)` function that is called for each slide, just after splitting the file, and receives the slide note as a string or undefined and the frontmatter of the slide as an object. The function can mutate the frontmatter and must return the note string (possibly modified, possibly `undefined` if no modifications have been done).
+  - a `name`
+
+## Example Preparser Extensions
+
+### Use case 1: compact syntax top-level presentation
+
+Imagine a situation where (part of) your presentation is mainly showing cover images and including other md files. You might want a compact notation where for instance (part of) `slides.md` is as follows:
+
+<!-- eslint-skip -->
+
+```md
+@cover: /nice.jpg
+# Welcome
+@src: page1.md
+@src: page2.md
+@cover: /break.jpg
+@src: pages3-4.md
+@cover: https://cover.sli.dev
+# Questions?
+see you next time
+```
+
+To allow these `@src:` and `@cover:` syntaxes, create a `./setup/preparser.ts` file with the following content:
+
+```ts twoslash
+import { definePreparserSetup } from '@slidev/types'
+
+export default definePreparserSetup(() => {
+  return [
+    {
+      transformRawLines(lines) {
+        let i = 0
+        while (i < lines.length) {
+          const l = lines[i]
+          if (l.match(/^@cover:/i)) {
+            lines.splice(
+              i,
+              1,
+              '---',
+              'layout: cover',
+              `background: ${l.replace(/^@cover: */i, '')}`,
+              '---',
+              ''
+            )
+            continue
+          }
+          if (l.match(/^@src:/i)) {
+            lines.splice(
+              i,
+              1,
+              '---',
+              `src: ${l.replace(/^@src: */i, '')}`,
+              '---',
+              ''
+            )
+            continue
+          }
+          i++
+        }
+      }
+    },
+  ]
+})
+```
+
+And that's it.
+
+### Use case 2: using custom frontmatter to wrap slides
+
+Imagine a case where you often want to scale some of your slides but still want to use a variety of existing layouts so creating a new layout would not be suited.
+For instance, you might want to write your `slides.md` as follows:
+
+<!-- eslint-skip -->
+
+```md
+---
+layout: quote
+_scale: 0.75
+---
+
+# Welcome
+
+> great!
+
+---
+_scale: 4
+---
+# Break
+
+---
+
+# Ok
+
+---
+layout: center
+_scale: 2.5
+---
+# Questions?
+see you next time
+```
+
+Here we used an underscore in `_scale` to avoid possible conflicts with existing frontmatter properties (indeed, the case of `scale`, without underscore would cause potential problems).
+
+To handle this `_scale: ...` syntax in the frontmatter, create a `./setup/preparser.ts` file with the following content:
+
+```ts twoslash
+import { definePreparserSetup } from '@slidev/types'
+
+export default definePreparserSetup(() => {
+  return [
+    {
+      async transformSlide(content, frontmatter) {
+        if ('_scale' in frontmatter) {
+          return [
+            `<Transform :scale=${frontmatter._scale}>`,
+            '',
+            content,
+            '',
+            '</Transform>'
+          ].join('\n')
+        }
+      },
+    },
+  ]
+})
+```
+
+And that's it.
+
+### Use case 3: using custom frontmatter to transform note
+
+Imagine a case where you want to replace the slides default notes with custom notes.
+For instance, you might want to write your `slides.md` as follows:
+
+<!-- eslint-skip -->
+
+```md
+---
+layout: quote
+_note: notes/note.md
+---
+
+# Welcome
+
+> great!
+
+<!--
+Default slide notes
+-->
+```
+
+Here we used an underscore in `_note` to avoid possible conflicts with existing frontmatter properties.
+
+To handle this `_note: ...` syntax in the frontmatter, create a `./setup/preparser.ts` file with the following content:
+
+```ts twoslash
+import fs, { promises as fsp } from 'node:fs'
+import { definePreparserSetup } from '@slidev/types'
+
+export default definePreparserSetup(() => {
+  return [
+    {
+      async transformNote(note, frontmatter) {
+        if ('_note' in frontmatter && fs.existsSync(frontmatter._note)) {
+          try {
+            const newNote = await fsp.readFile(frontmatter._note, 'utf8')
+            return newNote
+          }
+          catch (err) {
+          }
+        }
+
+        return note
+      },
+    },
+  ]
+})
+```

package/custom/config-routes.md

@@ -0,0 +1,28 @@
+# Configure Routes
+
+<Environment type="client" />
+
+Add custom pages to the Slidev app.
+
+## Usage
+
+Create `./setup/routes.ts` with the following content:
+
+```ts twoslash
+import { defineRoutesSetup } from '@slidev/types'
+
+export default defineRoutesSetup((routes) => {
+  return [
+    ...routes,
+    {
+      path: '/my-page',
+      // ---cut-start---
+      // @ts-expect-error missing types
+      // ---cut-end---
+      component: () => import('../pages/my-page.vue'),
+    },
+  ]
+})
+```
+
+Learn more about routes in the [Vue Router documentation](https://router.vuejs.org/).

package/custom/config-shortcuts.md

@@ -0,0 +1,36 @@
+# Configure Shortcuts
+
+<Environment type="client" />
+
+## Getting started
+
+Create `./setup/shortcuts.ts` with the following content:
+
+```ts twoslash
+import type { NavOperations, ShortcutOptions } from '@slidev/types'
+import { defineShortcutsSetup } from '@slidev/types'
+
+export default defineShortcutsSetup((nav: NavOperations, base: ShortcutOptions[]) => {
+  return [
+    ...base, // keep the existing shortcuts
+    {
+      key: 'enter',
+      fn: () => nav.next(),
+      autoRepeat: true,
+    },
+    {
+      key: 'backspace',
+      fn: () => nav.prev(),
+      autoRepeat: true,
+    },
+  ]
+})
+```
+
+In the setup function, you can customize the keyboard shortcuts by returning a new array of shortcuts. The above example binds the `next` operation to <kbd>enter</kbd> and the `prev` operation to <kbd>backspace</kbd>.
+
+Please refer to [Navigation Actions](../guide/ui#navigation-actions) section for the default shortcuts and navigation operations.
+
+## Key Binding Format
+
+The `key` of each shortcut can be either a string (e.g. `'Shift+Ctrl+A'`) or a computed boolean. Please refer to [`useMagicKeys` from VueUse](https://vueuse.org/core/useMagicKeys/) for

package/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

package/custom/config-unocss.md

@@ -0,0 +1,46 @@
+# Configure UnoCSS
+
+<Environment type="node" />
+
+[UnoCSS](https://unocss.dev) is now the default CSS framework for Slidev since v0.42.0. UnoCSS is a fast atomic CSS engine that has full flexibility and extensibility. Most of the Tailwind CSS classes are supported **out-of-box**, and you can also extend it with your own configurations.
+
+By default, Slidev enables the following presets out-of-box:
+
+- [@unocss/preset-wind3](https://unocss.dev/presets/wind3) - Tailwind / Windi CSS compatible utilities
+- [@unocss/preset-attributify](https://unocss.dev/presets/attributify) - Attributify mode
+- [@unocss/preset-icons](https://unocss.dev/presets/icons) - Use any icons as class
+- [@unocss/preset-web-fonts](https://unocss.dev/presets/web-fonts) - Use web fonts at ease
+- [@unocss/transformer-directives](https://unocss.dev/transformers/directives) - Use `@apply` in CSS
+
+Slidev also adds shortcuts as can be seen in its [source code](https://github.com/slidevjs/slidev/blob/main/packages/client/uno.config.ts).
+
+You can therefore style your content the way you want. For example:
+
+```html
+<div class="grid pt-4 gap-4 grid-cols-[100px,1fr]">
+
+### Name
+
+- Item 1
+- Item 2
+
+</div>
+```
+
+## Configurations
+
+You can create `uno.config.ts` under the root of your project to extend the builtin configurations
+
+```ts twoslash
+import { defineConfig } from 'unocss'
+
+export default defineConfig({
+  shortcuts: {
+    // custom the default background
+    'bg-main': 'bg-white text-[#181818] dark:(bg-[#121212] text-[#ddd])',
+  },
+  // ...
+})
+```
+
+Learn more about [UnoCSS configurations](https://unocss.dev/guide/config-file)

package/custom/config-vite.md

@@ -0,0 +1,83 @@
+# Configure Vite and Plugins
+
+<Environment type="node" />
+
+Slidev is powered by [Vite](https://vitejs.dev/) under the hood. This means you can leverage Vite's great plugin system to customize your slides even further.
+
+The `vite.config.ts` will be respected if you have one, and will be merged with the Vite config provided by Slidev, your theme and the addons.
+
+## Configure Internal Plugins
+
+Slidev internally adds the following plugins to Vite:
+
+- [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)
+- [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components)
+- [unplugin-icons](https://github.com/unplugin/unplugin-icons)
+- [vite-plugin-vue-markdown](https://github.com/unplugin/unplugin-vue-markdown)
+- [vite-plugin-remote-assets](https://github.com/antfu/vite-plugin-remote-assets)
+- [unocss/vite](https://github.com/unocss/unocss/tree/main/packages/vite)
+
+To configure the built-in plugins listed above, create a `vite.config.ts` with the following content. Please note that Slidev has some [default configurations](https://github.com/slidevjs/slidev/blob/main/packages/slidev/node/vite/index.ts) for those plugins, this usage will override some of them, which may potentially cause the app to break. Please treat this as **an advanced feature**, and make sure you know what you are doing before moving on.
+
+<!-- eslint-disable import/first -->
+
+```ts twoslash
+/// <reference types="@slidev/types" />
+import type MarkdownIt from 'markdown-it'
+declare const MyPlugin: (md: any) => void
+// ---cut---
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  slidev: {
+    vue: {
+      /* vue options */
+    },
+    markdown: {
+      /* markdown-it options */
+      markdownItSetup(md) {
+        /* custom markdown-it plugins */
+        md.use(MyPlugin)
+      },
+    },
+    /* options for other plugins */
+  },
+})
+```
+
+See the [type declarations](https://github.com/slidevjs/slidev/blob/main/packages/types/src/vite.ts#L11) for more options.
+
+::: warning
+It is not allowed to re-add plugins that has been used internally be Slidev. For example, instead of
+
+```ts twoslash
+import Vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    Vue({
+      /* vue options */
+    })
+  ],
+})
+```
+
+Please pass the Vue options to the `slidev.vue` field as described above
+:::
+
+## Add Custom Plugins based on Slide data
+
+Usually you can add Vite plugins into your `vite.config.ts` (see above).
+However, if you want to add plugins based on the slide data, you need to add a `./setup/vite-plugins.ts` with the following content:
+
+```ts twoslash
+import { defineVitePluginsSetup } from '@slidev/types'
+
+export default defineVitePluginsSetup((options) => {
+  return [
+    // Your plugins here
+    // Slide data is available as options.data.slides
+  ]
+})
+```

package/custom/config-vue.md

@@ -0,0 +1,25 @@
+# Configure Vue App
+
+<Environment type="client" />
+
+Slidev uses [Vue 3](https://v3.vuejs.org/) to render the application on the client side. You can extend the app to add custom plugins or configurations.
+
+Create `./setup/main.ts` with the following content:
+
+<!-- eslint-disable import/first -->
+
+```ts twoslash
+import type { Plugin } from 'vue'
+declare const YourPlugin: Plugin
+// ---cut---
+import { defineAppSetup } from '@slidev/types'
+
+export default defineAppSetup(({ app, router }) => {
+  // Vue App
+  app.use(YourPlugin)
+})
+```
+
+This can also be used as the main entrance of your Slidev app to do some initializations before the app starts.
+
+Learn more: [Vue Application API](https://v3.vuejs.org/api/application-api.html#component).

package/custom/directory-structure.md

@@ -0,0 +1,134 @@
+# Directory Structure
+
+Slidev employs some directory structure conventions to minimize the configuration surface and to make the functionality extensions flexible and intuitive.
+
+The conventional directory structure is:
+
+```bash
+your-slidev/
+  ├── components/       # custom components
+  ├── layouts/          # custom layouts
+  ├── public/           # static assets
+  ├── setup/            # custom setup / hooks
+  ├── snippets/         # code snippets
+  ├── styles/           # custom style
+  ├── index.html        # injections to index.html
+  ├── slides.md         # the main slides entry
+  └── vite.config.ts    # extending vite config
+```
+
+All of them are optional.
+
+## Components
+
+Pattern: `./components/*.{vue,js,ts,jsx,tsx,md}`
+
+<LinkCard link="guide/component" />
+
+## Layouts
+
+Pattern: `./layouts/*.{vue,js,ts,jsx,tsx}`
+
+<LinkCard link="guide/layout" />
+
+## Public
+
+Pattern: `./public/*`
+
+Assets in this directory will be served at root path `/` during dev, and copied to the root of the dist directory as-is. Read more about [Assets Handling](../guide/faq#assets-handling).
+
+## Style
+
+Pattern: `./style.css` | `./styles/index.{css,js,ts}`
+
+Files following this convention will be injected to the App root. If you need to import multiple CSS entries, you can create the following structure and manage the import order yourself.
+
+```bash
+your-slidev/
+  ├── ...
+  └── styles/
+      ├── index.ts
+      ├── base.css
+      ├── code.css
+      └── layouts.css
+```
+
+```ts
+// styles/index.ts
+
+import './base.css'
+import './code.css'
+import './layouts.css'
+```
+
+Styles will be processed by [UnoCSS](https://unocss.dev/) and [PostCSS](https://postcss.org/), so you can use CSS nesting and [at-directives](https://unocss.dev/transformers/directives#apply) and Nested CSS out-of-box. For example:
+
+<!-- eslint-skip -->
+
+```css
+.slidev-layout {
+  --uno: px-14 py-10 text-[1.1rem];
+
+  h1, h2, h3, h4, p, div {
+    --uno: select-none;
+  }
+
+  pre, code {
+    --uno: select-text;
+  }
+
+  a {
+    color: theme('colors.primary');
+  }
+}
+```
+
+Learn more about the syntax [here](https://unocss.dev/transformers/directives#apply).
+
+## `index.html`
+
+Pattern: `index.html`
+
+The `index.html` provides the ability to inject meta tags and/or scripts to the main `index.html`
+
+For example, for the following custom `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">
+</head>
+
+<body>
+  <script src="./your-scripts"></script>
+</body>
+```
+
+The final hosted `index.html` will be:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/slidevjs/slidev/assets/favicon.png">
+  <!-- injected 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">
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="__ENTRY__"></script>
+  <!-- injected body -->
+  <script src="./your-scripts"></script>
+</body>
+</html>
+```
+
+## Global Layers
+
+Pattern: `global-top.vue` | `global-bottom.vue` | `custom-nav-controls.vue` | `slide-top.vue` | `slide-bottom.vue`
+
+<LinkCard link="features/global-layers" />