@slidev/docs 51.6.2

package/features/frontmatter-merging.md

@@ -0,0 +1,49 @@
+---
+depends:
+  - guide/syntax#importing-slides
+  - features/importing-slides
+tags: [syntax]
+description: |
+  Merge frontmatter from multiple markdown files.
+---
+
+# Frontmatter Merging
+
+You can provide frontmatter instructions from both your main entry and external markdown pages. If there are duplicate keys in them, the ones from the **main entry have the higher priority**. For example:
+
+::: code-group
+
+```md [./slides.md]
+---
+src: ./cover.md
+background: https://sli.dev/bar.png // [!code highlight]
+class: text-center
+---
+```
+
+```md [./cover.md]
+---
+layout: cover
+background: https://sli.dev/foo.png // [!code highlight]
+---
+
+# Cover
+
+Cover Page
+```
+
+:::
+
+They will end up being equivalent to the following page:
+
+```md
+---
+layout: cover
+background: https://sli.dev/bar.png // [!code highlight]
+class: text-center
+---
+
+# Cover
+
+Cover Page
+```

package/features/global-layers.md

@@ -0,0 +1,99 @@
+---
+tags: [navigation, layout]
+description: |
+  Create custom components that persist across slides.
+---
+
+# Global Layers
+
+Global layers allow you to have custom components that **persist** across slides. This could be useful for having footers, cross-slide animations, global effects, etc.
+
+Slidev provides three layers for this usage, create `global-top.vue`, `global-bottom.vue`, or `custom-nav-controls.vue` under your project root and it will pick up automatically.
+
+There are also layers for **each** slide: `slide-top.vue` and `slide-bottom.vue`. The usage is similar to the global layers, but they are applied to every slide, so there may be more than one instance of them.
+
+::: tip
+If you are using `global-top.vue` or `global-bottom.vue` depending on the current navigation state, when exporting, the `--per-slide` option should be used to ensure the correct state is applied to each slide. Or you can use `slide-top.vue` and `slide-bottom.vue` instead.
+:::
+
+## Layers relationship
+
+At z-axis, from top to bottom:
+
+- NavControls
+  - Customized Navigation Controls (`custom-nav-controls.vue`)
+- Global Top (`global-top.vue`) - single instance
+- Slide Top (`slide-top.vue`) - instance per slide
+- Slide Content
+- Slide Bottom (`slide-bottom.vue`) - instance per slide
+- Global Bottom (`global-bottom.vue`) - single instance
+
+## Example
+
+```html
+<!-- global-bottom.vue -->
+<template>
+  <footer class="absolute bottom-0 left-0 right-0 p-2">Your Name</footer>
+</template>
+```
+
+The text `Your Name` will appear on all your slides.
+
+```html
+<!-- custom-nav-controls -->
+<template>
+  <button class="icon-btn" title="Next" @click="$nav.next">
+    <div class="i-carbon:arrow-right" />
+  </button>
+</template>
+```
+
+The button `Next` will appear in NavControls.
+
+To enable it conditionally, you can use the <LinkInline link="guide/global-context" />
+
+```html
+<!-- hide the footer from Page 4 -->
+<template>
+  <footer
+    v-if="$nav.currentPage !== 4"
+    class="absolute bottom-0 left-0 right-0 p-2"
+  >
+    Your Name
+  </footer>
+</template>
+```
+
+```html
+<!-- hide the footer from "cover" layout -->
+<template>
+  <footer
+    v-if="$nav.currentLayout !== 'cover'"
+    class="absolute bottom-0 left-0 right-0 p-2"
+  >
+    Your Name
+  </footer>
+</template>
+```
+
+```html
+<!-- an example footer for pages -->
+<template>
+  <footer
+    v-if="$nav.currentLayout !== 'cover'"
+    class="absolute bottom-0 left-0 right-0 p-2"
+  >
+    {{ $nav.currentPage }} / {{ $nav.total }}
+  </footer>
+</template>
+```
+
+```html
+<!-- custom-nav-controls -->
+<!-- hide the button in Presenter model -->
+<template>
+  <button v-if="!$nav.isPresenter" class="icon-btn" title="Next" @click="$nav.next">
+    <div class="i-carbon:arrow-right" />
+  </button>
+</template>
+```

package/features/icons.md

@@ -0,0 +1,58 @@
+---
+relates:
+  - Iconify: https://iconify.design/
+  - Icones: https://icones.js.org/
+  - unplugin-icons: https://github.com/antfu/unplugin-icons
+tags: [components]
+description: |
+  Use icons from virtually all open-source icon sets directly in your markdown.
+---
+
+# Icons
+
+Slidev allows you to have access to virtually all open-source icon sets **directly** in your markdown after installing the corresponding package. Powered by [`unplugin-icons`](https://github.com/antfu/unplugin-icons) and [Iconify](https://iconify.design/).
+
+The naming follows [Iconify](https://iconify.design/)'s convention of `{collection-name}-{icon-name}`. For example:
+
+- `<mdi-account-circle />` - <mdi-account-circle /> from [Material Design Icons](https://github.com/Templarian/MaterialDesign) - [`@iconify-json/mdi`](https://npmjs.com/package/@iconify-json/mdi)
+- `<carbon-badge />` - <carbon-badge /> from [Carbon](https://github.com/carbon-design-system/carbon/tree/main/packages/icons) - [`@iconify-json/carbon`](https://npmjs.com/package/@iconify-json/carbon)
+- `<uim-rocket />` - <uim-rocket /> from [Unicons Monochrome](https://github.com/Iconscout/unicons) - [`@iconify-json/uim`](https://npmjs.com/package/@iconify-json/uim)
+- `<twemoji-cat-with-tears-of-joy />` - <twemoji-cat-with-tears-of-joy /> from [Twemoji](https://github.com/twitter/twemoji) - [`@iconify-json/twemoji`](https://npmjs.com/package/@iconify-json/twemoji)
+- `<logos-vue />` - <logos-vue /> from [SVG Logos](https://github.com/gilbarbara/logos) - [`@iconify-json/logos`](https://npmjs.com/package/@iconify-json/logos)
+- And much more...
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @iconify-json/[the-collection-you-want]
+```
+
+```bash [npm]
+npm install @iconify-json/[the-collection-you-want]
+```
+
+```bash [yarn]
+yarn add @iconify-json/[the-collection-you-want]
+```
+
+```bash [bun]
+bun add @iconify-json/[the-collection-you-want]
+```
+
+:::
+
+We use [Iconify](https://iconify.design) as our data source of icons. You need to install the corresponding icon-set in `dependencies` by following the `@iconify-json/*` pattern. For example, `@iconify-json/mdi` for [Material Design Icons](https://materialdesignicons.com/), `@iconify-json/tabler` for [Tabler](https://tabler-icons.io/). You can refer to [Icônes](https://icones.js.org/) or [Iconify](https://icon-sets.iconify.design/) for all the collections available.
+
+### Styling Icons
+
+You can style the icons just like other HTML elements. For example:
+
+```html
+<uim-rocket />
+<uim-rocket class="text-3xl text-red-400 mx-2" />
+<uim-rocket class="text-3xl text-orange-400 animate-ping" />
+```
+
+<uim-rocket />
+<uim-rocket class="text-3xl text-red-400 mx-2" />
+<uim-rocket class="text-3xl text-orange-400 animate-ping ml-2" />

package/features/import-snippet.md

@@ -0,0 +1,48 @@
+---
+relates:
+  - features/monaco-write
+  - features/monaco-editor
+since: v0.47.0
+tags: [codeblock, syntax]
+description: |
+  Import code snippets from existing files into your slides.
+---
+
+# Import Code Snippets
+
+You can import code snippets from existing files via the following syntax:
+
+```md
+<<< @/snippets/snippet.js
+```
+
+::: tip
+The value of `@` corresponds to your package's root directory. It's recommended to put snippets in `@/snippets` in order to be compatible with the Monaco editor. Alternatively, you can also import from relative paths.
+:::
+
+You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file:
+
+```md
+<<< @/snippets/snippet.js#region-name
+```
+
+To explicitly specify the language of the imported code, you can add a language identifier after:
+
+```md
+<<< @/snippets/snippet.js ts
+```
+
+Any code block features like [line highlighting](#line-highlighting) and [Monaco editor](#monaco-editor) are also supported:
+
+```md
+<<< @/snippets/snippet.js {2,3|5}{lines:true}
+<<< @/snippets/snippet.js ts {monaco}{height:200px}
+```
+
+Note that you can use `{*}` as a placeholder of <LinkInline link="features/line-highlighting" />:
+
+<!-- eslint-skip -->
+
+```md
+<<< @/snippets/snippet.js {*}{lines:true}
+```

package/features/importing-slides.md

@@ -0,0 +1,69 @@
+---
+relates:
+  - features/frontmatter-merging
+tags: [syntax]
+description: |
+  Split your `slides.md` into multiple files for better reusability and organization.
+---
+
+# Importing Slides
+
+You can split your `slides.md` into multiple files for better reusability and organization. To do this, you can use the `src` frontmatter option to specify the path to the external markdown file. For example:
+
+::: code-group
+
+<!-- eslint-skip -->
+
+```md [./slides.md]
+# Title
+
+This is a normal page
+
+---
+src: ./pages/toc.md // [!code highlight]
+---
+
+<!-- this page will be loaded from './pages/toc.md' -->
+
+Contents here are ignored
+
+---
+
+# Page 4
+
+Another normal page
+
+---
+src: ./pages/toc.md   # Reuse the same file // [!code highlight]
+---
+```
+
+```md [./pages/toc.md]
+# Table of Contents
+
+Part 1
+
+---
+
+# Table of Contents
+
+Part 2
+```
+
+:::
+
+## Importing Specific Slides
+
+To reuse some of the slides inside another Markdown file, you can use the hash part of the import path:
+
+```md
+---
+src: ./another-presentation.md#2,5-7
+---
+```
+
+This will import the slides 2, 5, 6, and 7 from `./another-presentation.md`.
+
+## Frontmatter Merging
+
+<LinkCard link="features/frontmatter-merging" />

package/features/index.md

@@ -0,0 +1,93 @@
+---
+editLink: false
+footer: false
+aside: false
+outline: false
+sidebar: false
+pageClass: all-features-page
+---
+
+<script setup lang="ts">
+import { useUrlSearchParams } from '@vueuse/core'
+import { computed, toRef, ref } from 'vue'
+import { withBase } from 'vitepress'
+import { data as features } from './index.data'
+
+const query = useUrlSearchParams('hash-params', { removeFalsyValues: true })
+const search = toRef(query, 'search') as Ref<string | null>
+const tags = toRef(query, 'tags') as Ref<string | null>
+const tagsArr = computed({
+  get: () => tags.value?.toLowerCase().split(',').map(t => t.trim()).filter(Boolean) ?? [],
+  set: (val: string[]) => query.tags = val.join(','),
+})
+
+const filteredFeatures = computed(() => {
+  const s = search.value?.toLowerCase().trim()
+  const t = tagsArr.value
+  return Object.values(features).filter(feature => {
+    return (!s || feature.title.toLowerCase().includes(s) || feature.description.toLowerCase().includes(s))
+      && (!t?.length || t.every(tag => feature.tags?.includes(tag)))
+  })
+})
+
+function resetFilters() {
+  query.search = null
+  query.tags = null
+}
+
+function removeTag(tag: string) {
+  tagsArr.value = tagsArr.value.filter(t => t !== tag)
+}
+</script>
+
+# Features
+
+This is a list of all the individual features that Slidev provides. Each feature can be used independently and is optional.
+
+You can also read <LinkInline link="guide/" /> to learn the features by topic.
+
+<ClientOnly>
+<div flex items-center mt-6 gap-6>
+  <div
+    flex items-center rounded-md
+    px3 py2 gap-2 border-2 border-solid border-transparent
+    class="bg-$vp-c-bg-alt focus-within:border-color-$vp-c-brand"
+  >
+    <div class="i-carbon:search" text-sm op-80 />
+    <input
+      v-model="search"
+      type="search" text-base
+      placeholder="Search features..."
+    />
+  </div>
+  <div
+    v-if="tagsArr.length"
+    flex items-center gap-1
+  >
+    <div class="i-carbon:tag" text-sm mr-1 op-80 />
+    <FeatureTag v-for="tag in tagsArr" :key="tag" :tag removable @remove="removeTag(tag)"/>
+  </div>
+</div>
+
+<FeaturesOverview :features="filteredFeatures" />
+
+<div v-if="filteredFeatures.length === 0" class="w-full mt-6 op-80 flex flex-col items-center">
+  No results found
+  <button class="block select-button flex-inline gap-1 items-center px-2 py-1 hover:bg-gray-400/10 rounded" @click="resetFilters()">
+    <div class="i-carbon:filter-remove" />
+    Clear Filters
+  </button>
+</div>
+</ClientOnly>
+
+<style>
+.all-features-page .VPDoc > .container > .content {
+  max-width: 72vw !important;
+}
+</style>
+
+<style>
+:root {
+  overflow-y: scroll;
+}
+</style>

package/features/latex.md

@@ -0,0 +1,80 @@
+---
+relates:
+  - Demo: /demo/starter/11
+  - KaTeX: https://katex.org/
+tags: [codeblock, syntax]
+description: |
+  Slidev comes with LaTeX support out-of-box, powered by KaTeX.
+---
+
+# LaTeX
+
+Slidev comes with LaTeX support out-of-box, powered by [KaTeX](https://katex.org/).
+
+## Inline
+
+Surround your LaTeX with a single `$` on each side for inline rendering.
+
+```md
+$\sqrt{3x-1}+(1+x)^2$
+```
+
+## Block
+
+Use two (`$$`) for block rendering. This mode uses bigger symbols and centers
+the result.
+
+```latex
+$$
+\begin{aligned}
+\nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0} \\
+\nabla \cdot \vec{B} &= 0 \\
+\nabla \times \vec{E} &= -\frac{\partial\vec{B}}{\partial t} \\
+\nabla \times \vec{B} &= \mu_0\vec{J} + \mu_0\varepsilon_0\frac{\partial\vec{E}}{\partial t}
+\end{aligned}
+$$
+```
+
+## Line Highlighting
+
+To highlight specific lines, simply add line numbers within bracket `{}`. Line numbers start counting from 1 by default.
+
+```latex
+$$ {1|3|all}
+\begin{aligned}
+\nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0} \\
+\nabla \cdot \vec{B} &= 0 \\
+\nabla \times \vec{E} &= -\frac{\partial\vec{B}}{\partial t} \\
+\nabla \times \vec{B} &= \mu_0\vec{J} + \mu_0\varepsilon_0\frac{\partial\vec{E}}{\partial t}
+\end{aligned}
+$$
+```
+
+The `at` and `finally` options of [code blocks](#line-highlighting) are also available for LaTeX blocks.
+
+## Chemical equations
+
+To enable the rendering of chemical equations, the [mhchem](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem)
+KaTeX extension needs to be loaded.
+
+Create `vite.config.ts` with the following content:
+
+```ts
+import 'katex/contrib/mhchem'
+
+export default {}
+```
+
+Now chemical equations can be rendered properly.
+
+```latex
+$$
+\displaystyle{\ce{B(OH)3 + H2O <--> B(OH)4^- + H+}}
+$$
+```
+
+Learn more: [Syntax](https://mhchem.github.io/MathJax-mhchem)
+
+---
+
+<TheTweet id="1392246507793915904" />

package/features/line-highlighting.md

@@ -0,0 +1,57 @@
+---
+depends:
+  - guide/syntax#code-block
+  - guide/animations
+tags: [codeblock, animation]
+description: |
+  Highlight specific lines in code blocks based on clicks.
+---
+
+# Line Highlighting
+
+To highlight specific lines, simply add line numbers within brackets `{}`. Line numbers start counting from 1 by default.
+
+````md
+```ts {2,3}
+function add(
+  a: Ref<number> | number,
+  b: Ref<number> | number
+) {
+  return computed(() => unref(a) + unref(b))
+}
+```
+````
+
+## Dynamic Line Highlighting
+
+To change what's highlighted with multiple clicks, you can use `|` to separate each stage:
+
+````md
+```ts {2-3|5|all}
+function add(
+  a: Ref<number> | number,
+  b: Ref<number> | number
+) {
+  return computed(() => unref(a) + unref(b))
+}
+```
+````
+
+This will first highlight `a: Ref<number> | number` and `b: Ref<number> | number`, and then `return computed(() => unref(a) + unref(b))` after one click, and lastly, the whole block.
+
+You can set the line number to `hide` to hide the code block or `none` to not highlight any line:
+
+````md
+```ts {hide|none}
+function add(
+  a: Ref<number> | number,
+  b: Ref<number> | number
+) {
+  return computed(() => unref(a) + unref(b))
+}
+```
+````
+
+::: tip
+Learn more in the [click animations guide](/guide/animations#positioning).
+:::

package/features/mdc.md

@@ -0,0 +1,31 @@
+---
+relates:
+  - Nuxt's MDC Syntax: https://content.nuxt.com/docs/files/markdown#mdc-syntax
+  - markdown-it-mdc: https://github.com/antfu/markdown-it-mdc
+since: v0.43.0
+tags: [syntax, styling]
+description: |
+  A powerful syntax to enhance your markdown content with components and styles.
+---
+
+# MDC Syntax
+
+Slidev supports optional [MDC (Markdown Components) Syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax) powered by [`markdown-it-mdc`](https://github.com/antfu/markdown-it-mdc).
+
+You can enable it by adding `mdc: true` to the frontmatter of your markdown file.
+
+```mdc
+---
+mdc: true
+---
+
+This is a [red text]{style="color:red"} :inline-component{prop="value"}
+
+![](/image.png){width=500px lazy}
+
+::block-component{prop="value"}
+The **default** slot
+::
+```
+
+Learn more about [MDC Syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax).

package/features/mermaid.md

@@ -0,0 +1,37 @@
+---
+relates:
+  - Mermaid: https://mermaid.js.org/
+  - Mermaid Live Editor: https://mermaid.live/
+  - Demo Slide: https://sli.dev/demo/starter/12
+  - features/plantuml
+tags: [diagram]
+description: |
+  Create diagrams/graphs from textual descriptions, powered by Mermaid.
+---
+
+# Mermaid Diagrams
+
+You can also create diagrams/graphs from textual descriptions in your Markdown, powered by [Mermaid](https://mermaid.js.org/).
+
+Code blocks marked as `mermaid` will be converted to diagrams, for example:
+
+````md
+```mermaid
+sequenceDiagram
+  Alice->John: Hello John, how are you?
+  Note over Alice,John: A typical interaction
+```
+````
+
+You can further pass an options object to it to specify the scaling and theming. The syntax of the object is a JavaScript object literal, you will need to add quotes (`'`) for strings and use comma (`,`) between keys.
+
+````md
+```mermaid {theme: 'neutral', scale: 0.8}
+graph TD
+B[Text] --> C{Decision}
+C -->|One| D[Result 1]
+C -->|Two| E[Result 2]
+```
+````
+
+Visit the [Mermaid Website](https://mermaid.js.org/) for more information.

package/features/monaco-editor.md

@@ -0,0 +1,36 @@
+---
+depends:
+  - guide/syntax#code-block
+relates:
+  - Monaco Editor: https://microsoft.github.io/monaco-editor/
+  - Configure Monaco Editor: /custom/config-monaco
+tags: [codeblock, editor]
+description: |
+  Turn code blocks into fully-featured editors, or generate a diff between two code blocks.
+---
+
+# Monaco Editor
+
+<video src="https://github.com/slidevjs/slidev/assets/11247099/0c6ce681-80d3-4555-93bf-9288ee533462" controls rounded shadow w-full></video>
+
+Whenever you want to do some modification in the presentation, simply add `{monaco}` after the language id — it turns the block into a fully-featured Monaco editor!
+
+````md
+```ts {monaco}
+console.log('HelloWorld')
+```
+````
+
+Learn more about [Configuring Monaco](/custom/config-monaco).
+
+## Diff Editor
+
+Monaco can also generate a diff between two code blocks. Use `{monaco-diff}` to turn the block into a [Monaco diff editor](https://microsoft.github.io/monaco-editor/playground.html?source=v0.36.1#example-creating-the-diffeditor-multi-line-example) and use `~~~` to separate the original and modified code!
+
+````md
+```ts {monaco-diff}
+console.log('Original text')
+~~~
+console.log('Modified text')
+```
+````