@slidev/docs 51.6.2

package/builtin/layouts.md

@@ -0,0 +1,217 @@
+# Layouts
+
+This page lists all the built-in layouts provided by Slidev. These layouts can be used via the `layout` option in the frontmatters of your slides.
+
+Note that <LinkInline link="guide/theme-addon" /> may provide additional layouts or override the existing ones. To add your own layouts, see <LinkInline link="guide/write-layout" />.
+
+## `center`
+
+Displays the content in the middle of the screen.
+
+## `cover`
+
+Used to display the cover page for the presentation, may contain the presentation title, contextualization, etc.
+
+## `default`
+
+The most basic layout, to display any kind of content.
+
+## `end`
+
+The final page for the presentation.
+
+## `fact`
+
+To show some fact or data with a lot of prominence on the screen.
+
+## `full`
+
+Use all the space of the screen to display the content.
+
+## `image-left`
+
+Shows an image on the left side of the screen, the content will be placed on the right side.
+
+### Usage
+
+```yaml
+---
+layout: image-left
+
+# the image source
+image: /path/to/the/image
+
+# a custom class name to the content
+class: my-cool-content-on-the-right
+---
+```
+
+## `image-right`
+
+Shows an image on the right side of the screen, the content will be placed on the left side.
+
+### Usage
+
+```yaml
+---
+layout: image-right
+
+# the image source
+image: /path/to/the/image
+
+# a custom class name to the content
+class: my-cool-content-on-the-left
+---
+```
+
+## `image`
+
+Shows an image as the main content of the page.
+
+### Usage
+
+```yaml
+---
+layout: image
+
+# the image source
+image: /path/to/the/image
+---
+```
+
+You can change the default background size (`cover`) by adding the `backgroundSize` attribute:
+
+```yaml
+---
+layout: image
+image: /path/to/the/image
+backgroundSize: contain
+---
+```
+
+```yaml
+---
+layout: image-left
+image: /path/to/the/image
+backgroundSize: 20em 70%
+---
+```
+
+## `iframe-left`
+
+Shows a web page on the left side of the screen, the content will be placed on the right side.
+
+### Usage
+
+```yaml
+---
+layout: iframe-left
+
+# the web page source
+url: https://github.com/slidevjs/slidev
+
+# a custom class name to the content
+class: my-cool-content-on-the-right
+---
+```
+
+## `iframe-right`
+
+Shows a web page on the right side of the screen, the content will be placed on the left side.
+
+### Usage
+
+```yaml
+---
+layout: iframe-right
+
+# the web page source
+url: https://github.com/slidevjs/slidev
+
+# a custom class name to the content
+class: my-cool-content-on-the-left
+---
+```
+
+## `iframe`
+
+Shows a web page as the main content of the page.
+
+### Usage
+
+```yaml
+---
+layout: iframe
+
+# the web page source
+url: https://github.com/slidevjs/slidev
+---
+```
+
+## `intro`
+
+To introduce the presentation, usually with the presentation title, a short description, the author, etc.
+
+## `none`
+
+A layout without any existing styling.
+
+## `quote`
+
+To display a quotation with prominence.
+
+## `section`
+
+Used to mark the beginning of a new presentation section.
+
+## `statement`
+
+Make an affirmation/statement as the main page content.
+
+## `two-cols`
+
+Separates the page content in two columns.
+
+### Usage
+
+```md
+---
+layout: two-cols
+---
+
+# Left
+
+This shows on the left
+
+::right::
+
+# Right
+
+This shows on the right
+```
+
+## `two-cols-header`
+
+Separates the upper and lower lines of the page content, and the second line separates the left and right columns.
+
+### Usage
+
+```md
+---
+layout: two-cols-header
+---
+
+This spans both
+
+::left::
+
+# Left
+
+This shows on the left
+
+::right::
+
+# Right
+
+This shows on the right
+```

package/custom/config-code-runners.md

@@ -0,0 +1,78 @@
+# Configure Code Runners
+
+<Environment type="client" />
+
+Define code runners for custom languages in your Monaco Editor.
+
+By default, JavaScript, TypeScript runners are supported built-in. They run in the browser **without** a sandbox environment. If you want more advanced integrations, you can provide your own code runner that sends the code to a remote server, runs in a Web Worker, or anything, up to you.
+
+Create `./setup/code-runners.ts` with the following content:
+
+<!-- eslint-disable import/first -->
+
+```ts twoslash
+declare const executePythonCodeRemotely: (code: string) => Promise<string>
+declare const sanitizeHtml: (html: string) => string
+// ---cut---
+import { defineCodeRunnersSetup } from '@slidev/types'
+
+export default defineCodeRunnersSetup(() => {
+  return {
+    async python(code, ctx) {
+      // Somehow execute the code and return the result
+      const result = await executePythonCodeRemotely(code)
+      return {
+        text: result
+      }
+    },
+    html(code, ctx) {
+      return {
+        html: sanitizeHtml(code)
+      }
+    },
+    // or other languages, key is the language id
+  }
+})
+```
+
+## Runner Context
+
+The second argument `ctx` is the runner context, which contains the following properties:
+
+```ts twoslash
+import type { CodeRunnerOutputs } from '@slidev/types'
+import type { CodeToHastOptions } from 'shiki'
+// ---cut---
+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>) => 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.
+
+## Additional Runner Dependencies
+
+By default, Slidev will scan the Markdown source and automatically import the necessary dependencies for the code runners. If you want to manually import dependencies, you can use the `monacoRunAdditionalDeps` option in the slide frontmatter:
+
+```yaml
+monacoRunAdditionalDeps:
+  - ./path/to/dependency
+  - lodash-es
+```
+
+::: tip
+The paths are resolved relative to the `snippets` directory. And the names of the deps should be exactly the same as the imported ones in the code.
+:::

package/custom/config-context-menu.md

@@ -0,0 +1,40 @@
+# Configure Context Menu
+
+<Environment type="client" />
+
+Customize the context menu items in Slidev.
+
+Create `./setup/context-menu.ts` with the following content:
+
+<!-- eslint-disable import/first -->
+
+```ts twoslash
+// ---cut---
+import { useNav } from '@slidev/client'
+import { defineContextMenuSetup } from '@slidev/types'
+import { computed } from 'vue'
+// ---cut-start---
+// @ts-expect-error missing types
+// ---cut-end---
+import Icon3DCursor from '~icons/carbon/3d-cursor'
+
+export default defineContextMenuSetup((items) => {
+  const { isPresenter } = useNav()
+  return computed(() => [
+    ...items.value,
+    {
+      small: false,
+      icon: Icon3DCursor, // if `small` is `true`, only the icon is shown
+      label: 'Custom Menu Item', // or a Vue component
+      action() {
+        alert('Custom Menu Item Clicked!')
+      },
+      disabled: isPresenter.value,
+    },
+  ])
+})
+```
+
+This will append a new menu item to the context menu.
+
+To disable context menu globally, set `contextMenu` to `false` in the frontmatter. `contextMenu` can also be set to `dev` or `build` to only enable the context menu in development or build mode.

package/custom/config-fonts.md

@@ -0,0 +1,105 @@
+# Configure Fonts
+
+While you can use HTML and CSS to customize the fonts and style for your slides as you want, Slidev also provides a convenient way to use them effortlessly.
+
+In your frontmatter, configure as the following:
+
+```yaml
+---
+fonts:
+  # basically the text
+  sans: Robot
+  # use with `font-serif` css class from UnoCSS
+  serif: Robot Slab
+  # for code blocks, inline code, etc.
+  mono: Fira Code
+---
+```
+
+And that's all.
+
+Fonts will be **imported automatically from a provider via CDN, by default it is [Google Fonts](https://fonts.google.com/)**. That means you can use any fonts available on Google Fonts directly.
+
+## Local Fonts
+
+By default, Slidev assumes all the fonts specified via `fonts` configurations come from Google Fonts. If you want to use local fonts, specify the `fonts.local` to opt-out the auto-importing.
+
+```yaml
+---
+fonts:
+  # like font-family in css, you can use `,` to separate multiple fonts for fallback
+  sans: 'Helvetica Neue,Robot'
+  # mark 'Helvetica Neue' as local font
+  local: Helvetica Neue
+---
+```
+
+## Weights & Italic
+
+By default, Slidev imports three weights `200`,`400`,`600` for each font. You can configure them by:
+
+```yaml
+---
+fonts:
+  sans: Robot
+  # default
+  weights: '200,400,600'
+  # import italic fonts, default `false`
+  italic: false
+---
+```
+
+This configuration applies to all web fonts. For more fine-grained controls of each font's weights, you will need to manually import them with [HTML](/custom/directory-structure.html#index-html) and CSS.
+
+## Fallback Fonts
+
+For most of the scenarios, you only need to specify the "special font" and Slidev will append the fallback fonts for you, for example:
+
+```yaml
+---
+fonts:
+  sans: Robot
+  serif: Robot Slab
+  mono: Fira Code
+---
+```
+
+will result in
+
+<!-- eslint-skip -->
+
+```css
+.font-sans {
+  font-family: "Robot",ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+}
+.font-serif {
+  font-family: "Robot Slab",ui-serif,Georgia,Cambria,"Times New Roman",Times,serif;
+}
+.font-mono {
+  font-family: "Fira Code",ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;
+}
+```
+
+If you want to disable the fallback fonts, configure as the following:
+
+```yaml
+---
+fonts:
+  mono: 'Fira Code, monospace'
+  fallbacks: false
+---
+```
+
+## Providers
+
+- Options: `google` | `coollabs` | `none`
+- Default: `google`
+
+Currently, only [Google Fonts](https://fonts.google.com/) and [coolLabs](https://fonts.coollabs.io/) supported, we are planning to add more providers in the future. Specify to `none` will disable the auto-importing feature entirely and treat all the fonts locally.
+
+```yaml
+---
+fonts:
+  provider: none
+---
+```

package/custom/config-highlighter.md

@@ -0,0 +1,74 @@
+# Configure Highlighter
+
+Slidev uses [Shiki](https://github.com/shikijs/shiki) as the code highlighter. It's a TextMate Grammar powered syntax highlighter as accurate as VS Code. It generates colored tokens so no additinal CSS is required. Shiki also comes with [a bunch of built-in themes](https://shiki.style/themes). In Slidev, we also provided the [TwoSlash](#twoslash-integration) support.
+
+## Configure Shiki
+
+<Environment type="both" />
+
+Create `./setup/shiki.ts` file with the following content:
+
+```ts twoslash
+/* ./setup/shiki.ts */
+import { defineShikiSetup } from '@slidev/types'
+
+export default defineShikiSetup(() => {
+  return {
+    themes: {
+      dark: 'min-dark',
+      light: 'min-light',
+    },
+    transformers: [
+      // ...
+    ],
+  }
+})
+```
+
+If you want to add custom theme or language (TextMate grammar/themes in JSON), you can import them in the setup file:
+
+<!-- eslint-disable import/first-->
+
+```ts twoslash
+/* ./setup/shiki.ts */
+import { defineShikiSetup } from '@slidev/types'
+// ---cut-start---
+// @ts-expect-error missing types
+// ---cut-end---
+import customLanguage from './customLanguage.tmLanguage.json'
+// ---cut-start---
+// @ts-expect-error missing types
+// ---cut-end---
+import customTheme from './customTheme.tmTheme.json'
+
+export default defineShikiSetup(() => {
+  return {
+    themes: {
+      dark: customTheme,
+      light: 'min-light',
+    },
+    langs: [
+      'js',
+      'typescript',
+      'cpp',
+      customLanguage,
+      // ...
+    ],
+    transformers: [
+      // ...
+    ],
+  }
+})
+```
+
+Check [Built-in languages](https://shiki.style/languages) and [Built-in themes](https://shiki.style/themes), and refer to [Shiki's docs](https://shiki.style) for more details.
+
+:::info
+For now, Shiki Magic Move does not support transformers.
+:::
+
+## Configure Prism
+
+:::warning
+Prism support has been removed since v0.50. Please use Shiki instead.
+:::

package/custom/config-katex.md

@@ -0,0 +1,18 @@
+# Configure KaTeX
+
+<Environment type="node" />
+
+Create `./setup/katex.ts` with the following content:
+
+```ts twoslash
+import { defineKatexSetup } from '@slidev/types'
+
+export default defineKatexSetup(() => {
+  return {
+    maxExpand: 2000,
+    /* ... */
+  }
+})
+```
+
+The return value should be the custom options for KaTeX. Refer to [KaTeX's documentation](https://katex.org/docs/options.html) or the type definition for the full options list.

package/custom/config-mermaid.md

@@ -0,0 +1,47 @@
+# Configure Mermaid
+
+<Environment type="client" />
+
+Create `./setup/mermaid.ts` with the following content:
+
+```ts twoslash
+import { defineMermaidSetup } from '@slidev/types'
+
+export default defineMermaidSetup(() => {
+  return {
+    theme: 'forest',
+  }
+})
+```
+
+The return value should be the custom configs for [Mermaid](https://mermaid.js.org/). Refer to the [Mermaid documentation](https://mermaid.js.org/config/schema-docs/config.html) or the type definition for the full config list.
+
+## Custom theme/styles
+
+In case you want to create your custom Mermaid themes or styles, you can do this by defining `themeVariables` like in the following example:
+
+```ts twoslash
+import { defineMermaidSetup } from '@slidev/types'
+
+export default defineMermaidSetup(() => {
+  return {
+    theme: 'base',
+    themeVariables: {
+      // General theme variables
+      noteBkgColor: '#181d29',
+      noteTextColor: '#F3EFF5cc',
+      noteBorderColor: '#404551',
+
+      // Sequence diagram variables
+      actorBkg: '#0E131F',
+      actorBorder: '#44FFD2',
+      actorTextColor: '#F3EFF5',
+      actorLineColor: '#F3EFF5',
+      signalColor: '#F3EFF5',
+      signalTextColor: '#F3EFF5',
+    }
+  }
+})
+```
+
+You can find all theme variables on the [Mermaid Theme Configuration](https://mermaid.js.org/config/theming.html) page.

package/custom/config-monaco.md

@@ -0,0 +1,99 @@
+# Configure Monaco
+
+<Environment type="client" />
+
+Create `./setup/monaco.ts` with the following content:
+
+```ts twoslash
+import { defineMonacoSetup } from '@slidev/types'
+
+export default defineMonacoSetup(async (monaco) => {
+  // use `monaco` to configure
+})
+```
+
+Learn more about [configuring Monaco](https://github.com/Microsoft/monaco-editor).
+
+## TypeScript Types
+
+When using TypeScript with Monaco, types for dependencies will be installed to the client-side automatically.
+
+````md
+```ts {monaco}
+import { ref } from 'vue'
+import { useMouse } from '@vueuse/core'
+
+const counter = ref(0)
+```
+````
+
+In the example above, make sure `vue` and `@vueuse/core` are installed locally as dependencies / devDependencies, Slidev will handle the rest to get the types working for the editor automatically. When deployed as SPA, those types will also be bundled for static hosting.
+
+### Additional Types
+
+Slidev will scan all the Monaco code blocks in your slides and import the types for those used libraries for you. In case it missed some, you can explicitly specify extra packages to import the types for:
+
+```md
+---
+monacoTypesAdditionalPackages:
+  - lodash-es
+  - foo
+---
+```
+
+### Auto Type Acquisition
+
+You can optionally switch to load types from CDN by setting the following headmatter:
+
+```md
+---
+monacoTypesSource: ata
+---
+```
+
+This feature is powered by [`@typescript/ata`](https://github.com/microsoft/TypeScript-Website/tree/v2/packages/ata) and runs completely on the client-side.
+
+## Configure Themes
+
+Since v0.48.0, Monaco will reuse the Shiki theme you configured in [Shiki's setup file](/custom/config-highlighter#configure-shiki), powered by [`@shikijs/monaco`](https://shiki.style/packages/monaco). You don't need to worry about it anymore and it will have a consistent style with the rest of your code blocks.
+
+## Configure the Editor
+
+> Available since v0.43.0
+
+If you would like to customize the Monaco editor you may pass an `editorOptions` object that matches the [Monaco IEditorOptions](https://microsoft.github.io/monaco-editor/docs.html#interfaces/editor.IEditorOptions.html) definition.
+
+````md
+```ts {monaco} { editorOptions: { wordWrap:'on'} }
+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
+import { defineMonacoSetup } from '@slidev/types'
+
+export default defineMonacoSetup(() => {
+  return {
+    editorOptions: {
+      wordWrap: 'on'
+    }
+  }
+})
+```
+
+## Disabling
+
+Since v0.48.0, the Monaco editor is enabled by default and only be bundled when you use it. If you want to disable it, you can set `monaco` to `false` in the frontmatter of your slide:
+
+```yaml
+---
+monaco: false # can also be `dev` or `build` to conditionally enable it
+---
+```
+
+## Configure Code Runners
+
+To configure how the Monaco Runner runs the code, or to add support for custom languages, please reference [Configure Code Runners](/custom/config-code-runners).