@slidev/docs 51.6.2

package/guide/ui.md

@@ -0,0 +1,86 @@
+---
+outline: deep
+---
+
+# User Interface
+
+## Navigation Bar {#navigation-bar}
+
+In Play mode, move your mouse to the bottom left corner of the page, you can see the navigation bar.
+![](/screenshots/navbar.png)
+
+> You can extend the navigation bar via <LinkInline link="features/global-layers" />.
+
+## Navigation Actions {#navigation-actions}
+
+| Keyboard Shortcut                   | Button in Navigation Bar                                                              | Description                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| <kbd>f</kbd>                        | <carbon-maximize class="inline-icon-btn"/> <carbon-minimize class="inline-icon-btn"/> | Toggle fullscreen                                               |
+| <kbd>right</kbd> / <kbd>space</kbd> | <carbon-arrow-right class="inline-icon-btn"/>                                         | Next animation or slide                                         |
+| <kbd>left</kbd>                     | <carbon-arrow-left class="inline-icon-btn"/>                                          | Previous animation or slide                                     |
+| <kbd>up</kbd>                       | -                                                                                     | Previous slide                                                  |
+| <kbd>down</kbd>                     | -                                                                                     | Next slide                                                      |
+| <kbd>o</kbd>                        | <carbon-apps class="inline-icon-btn"/>                                                | Toggle [Quick Overview](#quick-overview)                        |
+| <kbd>d</kbd>                        | <carbon-sun class="inline-icon-btn"/> <carbon-moon class="inline-icon-btn"/>          | Toggle dark mode                                                |
+| -                                   | <carbon-user-avatar class="inline-icon-btn"/>                                         | Toggle [Camera View](../features/recording#camera-view)         |
+| -                                   | <carbon-video class="inline-icon-btn"/>                                               | Start <LinkInline link="features/recording" />                  |
+| -                                   | <carbon-user-speaker class="inline-icon-btn"/>                                        | Enter [Presenter Mode](#presenter-mode)                         |
+| -                                   | <carbon-text-annotation-toggle class="inline-icon-btn"/>                              | Toggle <LinkInline link="features/side-editor" />               |
+| -                                   | <carbon-document-pdf class="inline-icon-btn"/>                                        | Enter [Browser Exporter](#exporter)                             |
+| -                                   | <carbon-download class="inline-icon-btn"/>                                            | Download PDF. See <LinkInline link="features/build-with-pdf" /> |
+| -                                   | <carbon-information class="inline-icon-btn"/>                                         | Show information about the slides                               |
+| -                                   | <carbon-settings-adjust class="inline-icon-btn"/>                                     | More options                                                    |
+| <kbd>g</kbd>                        | -                                                                                     | Show goto...                                                    |
+
+> You can [configure the shortcuts](../custom/config-shortcuts).
+
+## Quick Overview {#quick-overview}
+
+By pressing <kbd>o</kbd> or clicking the <carbon-apps class="inline-icon-btn"/> button in the navigation bar, you can have an overview of your slides so you can jump between them easily.
+
+![](/screenshots/slides-overview.png)
+
+## Presenter Mode {#presenter-mode}
+
+To enter the presenter mode, you can click the <carbon-user-speaker class="inline-icon-btn"/> button in the navigation panel, or visit `http://localhost:<port>/presenter`.
+
+When giving a presentation, it's recommended to open two browser windows - one in the play mode for the audience, and another one in the presenter mode for you. Then you can share the first screen to the audience and keep the second screen for yourself.
+
+Whenever you navigate through the slides in the presenter mode, all other opened pages will automatically follow this navigation to stay in sync with the presenter.
+
+![](/screenshots/presenter-mode.png)
+
+## Slide Overview {#slides-overview}
+
+> Available since v0.48.0
+
+<video src="https://github.com/slidevjs/slidev/assets/11247099/01bbf5b3-f916-4646-9ea4-cf269c0567cb"
+controls rounded shadow></video>
+
+You can visit an overview of all of your slides by first opening the [Quick Overview panel](#quick-overview) and then clicking the <carbon-list-boxes class="inline-icon-btn"/> on the top right, or by visiting `http://localhost:<port>/overview` directly.
+
+The overview page gives you a linear list of all your slides, with all of your notes on the side. You can double-click on the notes to edit the notes directly, and drag the clicks sliders to preview the steps in your slides.
+
+## Drawing UI {#drawing}
+
+See:
+
+<LinkCard link="features/drawing" />
+
+## Recording UI {#recording}
+
+See:
+
+<LinkCard link="features/recording"/>
+
+## Browser Exporter {#exporter}
+
+See:
+
+<LinkCard link="guide/exporting#browser"/>
+
+## Global Layers {#global-layers}
+
+You can add any custom UI below or above your slides for the whole presentation or per-slide:
+
+<LinkCard link="features/global-layers" />

package/guide/why.md

@@ -0,0 +1,112 @@
+---
+outline: deep
+---
+
+# Why Slidev
+
+There have been lots of feature-rich WYSIWYG slides makers like [Microsoft PowerPoint](https://www.microsoft.com/en-us/microsoft-365/powerpoint) and [Apple Keynote](https://www.apple.com/keynote/) _(see [Comparisons](#comparisons))_. They are intuitive and easy to learn. So why bother making Slidev?
+
+Slidev aims to provide flexibility and interactivity for **developers** to make their presentations much more interesting, expressive, and attractive by using technologies they are familiar with. Slidev is also open source with a strong community.
+
+Slidev is Markdown-based, which helps you **focus on the content**. Slidev is also Web-based, which means **nothing is impossible** - everything you can do in a web app can apply to your slides.
+
+Slidev is also **progressive**. You can start with a super simple Markdown file, and then use the [built-in features](../features/) when you need them without any configuration. There are also [themes and addons](./theme-addon) you can optionally install to enhance your slides.
+
+![demo slide](/screenshots/cover.png) {#welcome}
+
+## Features
+
+### 📝 Markdown-based
+
+Slidev uses an extended Markdown format to organize your slides in a single plain text file. This helps you focus on the content while allowing you to use Git and any editor you like.
+
+> Learn more: <LinkInline link="guide/syntax"/>.
+
+### 🧑‍💻 Developer Friendly
+
+Slidev provides first-class support for code snippets for developers. It uses [Shiki](https://github.com/shikijs/shiki) to get the most accurate syntax highlighting. Slidev also supports <LinkInline link="features/shiki-magic-move"/> and <LinkInline link="features/twoslash"/>. These make Slidev the best choice for tech talks.
+
+### 🎨 Themable
+
+Themes for Slidev can be shared via npm packages. You apply a theme within one line of code.
+
+Check out the [Theme Gallery](../resources/theme-gallery) for the beautiful themes made by the official team and the community.
+
+### ⚡ Fast
+
+Every change you make in the editor will be updated to your slides in the browser **instantly** without reloading, thanks to [Vite's HMR feature](https://vitejs.dev/guide/features.html#hot-module-replacement).
+
+### 🤹 Interactive & Expressive
+
+You can write Vue components and use them in your slides, which you can then interact with during the presentation to express your idea in a more interesting and intuitive way.
+
+Slidev also has built-in support of <LinkInline link="features/monaco-editor"/>, which empowers you to do live coding in your presentation with auto-completion and hover messages.
+
+### 🎥 Recording Support
+
+Slidev provides built-in recording and camera view. You can share your presentation with your camera view inside, or record and save your screen and camera separately.
+
+> Learn more: <LinkInline link="features/recording"/>.
+
+### 📤 Portable
+
+You can export your slides into PDF, PPTX, PNGs, or even a single-page application (SPA) via a single command. Then you can share or host it anywhere you like.
+
+> Learn more: <LinkInline link="guide/exporting"/> and <LinkInline link="guide/hosting"/>.
+
+### 🛠 Hackable
+
+Because Slidev is web-based, everything that can be done in a normal web app can be applied to your slides. For example, WebGL, API requests, iframes, or even live sharing. It's up to your imagination!
+
+> Learn more: [Customization](../custom/).
+
+## Comparisons
+
+::: details Slidev vs. Microsoft PowerPoint / Apple Keynote
+
+[Microsoft PowerPoint](https://www.microsoft.com/en-us/microsoft-365/powerpoint) and [Apple Keynote](https://www.apple.com/keynote/) are feature-rich WYSIWYG slides makers. They are intuitive and easy to learn, which makes them one of the best choices for non-developers.
+
+Compared to them, Slidev has the following advantages:
+
+- Developer-friendly: Code snippets are first-class citizens in Slidev.
+- Markdown-based: Focus on the content, and version control your slides with Git.
+- Web-based: Everything you can do in a web app can apply to your slides.
+- Hackable: Customize anything you like with web technologies.
+- Open source: Slidev is completely open source, and has a strong community.
+
+:::
+
+::: details Slidev vs. Reveal.js
+
+[Reveal.js](https://revealjs.com/) is a popular HTML presentation framework. It is also open source and supports Markdown.
+
+Compared to Reveal.js, Slidev has the following advantages:
+
+- More concise: Slidev uses an extended Markdown format, while Reveal.js encourages you to write HTML to organize your slides.
+- Vue support: You can use Vue components in Slidev to make your slides interactive.
+- Vite-based: Slidev is built on top of Vite, which provides instant HMR and flexible plugin API.
+- Atomatic CSS: You can [UnoCSS](https://unocss.dev/) out of the box to style your slides.
+
+:::
+
+::: details Slidev vs. Marp
+
+[Marp](https://marp.app/) is a Markdown presentation tool that focuses on simplicity and portability. It is also open source and supports Markdown.
+
+Compared to Marp, Slidev has the following advantages:
+
+- The same simplicity: Slidev's slides can start as simple as Marp's.
+- More features: Slidev supports many features that Marp doesn't.
+- Vue support: You can use Vue components in Slidev to make your slides interactive.
+- Vite-based: Slidev is built on top of Vite, which provides instant HMR and flexible plugin API.
+- Atomatic CSS: You can [UnoCSS](https://unocss.dev/) out of the box to style your slides.
+
+:::
+
+## Give it a Try
+
+Playing around with Slidev will tell you more than thousands of words. Check the <LinkInline link="guide/"/> guide to create your first Slidev project in one click or one command.
+
+Or you can have a quick preview of it:
+
+<iframe class="aspect-16/9 rounded-xl w-full shadow-md border-none" src="https://www.youtube.com/embed/eW7v-2ZKZOU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

package/guide/write-addon.md

@@ -0,0 +1,48 @@
+# Writing Addons
+
+> Please read <LinkInline link="guide/theme-addon" /> and <LinkInline link="guide/write-theme" /> first.
+
+Each slides project can only have one theme, but can have multiple addons.
+
+## Capability
+
+Theoretically, all the capabilities of a theme can be done in an addon. However, an addon is more like a plugin that extends the functionalities of Slidev.
+
+It's recommended to implement one or more of the following points in an addon:
+
+- Provide custom components
+- Provide _new_ layouts
+- Provide new code snippets
+- Provide new code runners
+- Configure tools like UnoCSS, Vite, etc.
+
+However, the following points are **not** recommended to be done in an addon, and may be better [implemented as a theme](./write-theme):
+
+- Wildcard global styles
+- Overriding existing layouts
+- Overriding configurations
+- Other things that may be incompatible with the theme and other addons
+
+An addon can also specify its required Slidev version in the same way as themes.
+
+## Previewing
+
+The same as themes, you can preview your addon via a `./slides.md` like this:
+
+```md
+---
+addons:
+  - ./
+---
+```
+
+## Publishing
+
+When publishing the addon, non-JS files like `.vue` and `.ts` files can be published directly without compiling. Slidev will automatically compile them when using the addon.
+
+Addons should follow the following conventions:
+
+- Package name should start with `slidev-addon-`. For example, `slidev-addon-name` or `@scope/slidev-addon-name`
+- Add `"slidev-addon"` and `"slidev"` in the `keywords` field of your `package.json`
+
+Theme can be used locally without publishing to NPM. If your addon is only for personal use, you can simply use it as a local addon, or publish it as a private scoped package. However, it is recommended to publish it to the NPM registry if you want to share it with others.

package/guide/write-layout.md

@@ -0,0 +1,45 @@
+# Writing Layouts
+
+> Please read <LinkInline link="guide/layout" /> first.
+
+To create a custom layout, simply create a new Vue file in the `layouts` directory:
+
+```bash
+your-slidev/
+  ├── ...
+  ├── slides.md
+  └── layouts/
+      ├── ...
+      └── MyLayout.vue
+```
+
+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 -->
+<template>
+  <div class="slidev-layout default">
+    <slot />
+  </div>
+</template>
+```
+
+You can also have [named slots](https://vuejs.org/guide/components/slots.html) for more complex layouts:
+
+```vue
+<!-- split.vue -->
+<template>
+  <div class="slidev-layout split">
+    <div class="left">
+      <slot name="left" />
+    </div>
+    <div class="right">
+      <slot name="right" />
+    </div>
+  </div>
+</template>
+```
+
+And then use it with <LinkInline link="features/slot-sugar" />.

package/guide/write-theme.md

@@ -0,0 +1,109 @@
+# Writing Themes
+
+> Please read <LinkInline link="guide/theme-addon" /> first.
+
+Each slides project can only have one theme. Themes should focus on providing the appearance of slides. If the feature isn't related to the appearance and can be used separately, it should be implemented as an [addon](./write-addon).
+
+To get started, we recommend you use our generator for scaffolding your first theme
+
+::: code-group
+
+```bash [pnpm]
+$ pnpm create slidev-theme
+```
+
+```bash [npm]
+$ npm init slidev-theme@latest
+```
+
+```bash [yarn]
+$ yarn create slidev-theme
+```
+
+```bash [bun]
+$ bun create slidev-theme
+```
+
+:::
+
+Then you can modify and play with it. You can also refer to the [official themes](../resources/theme-gallery#official-themes) as examples.
+
+## Capability
+
+A theme can contribute to the following points:
+
+- Global styles
+- Provide default configurations
+- Provide custom layouts or override the existing ones
+- Provide custom components
+- Configure tools like UnoCSS, Shiki, etc.
+
+However, the following points are **not** recommended to be done in a theme, and may be better implemented as an [addon](./write-addon):
+
+- New code snippets
+- New code runners
+- Other things that can be used separately
+
+Basically, the way to provide global styles, layouts, components and configure tools is the same as doing these in a slides project. For example, to configure Shiki, you can create a `./setup/shiki.ts` as described in [Configure Highlighter](../custom/config-highlighter). You can refer to the [customization guide](/custom/) for more information.
+
+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
+{
+  "slidev": {
+    "defaults": {
+      "transition": "slide-left",
+      "aspectRatio": "4/3"
+    }
+  }
+}
+```
+
+### Require Slidev Version
+
+If the theme is relying on a specific feature of Slidev that is newly introduced, you can set the minimal Slidev version required to have your theme working properly:
+
+```json
+{
+  "engines": {
+    "slidev": ">=0.48.0"
+  }
+}
+```
+
+An error message will be shown when the an incompatible version is used.
+
+### Theme Metadata
+
+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
+{
+  "slidev": {
+    "colorSchema": "light" // or "dark" or "both"
+  }
+}
+```
+
+## Previewing
+
+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
+---
+theme: ./  # Use the theme in the current directory
+---
+```
+
+Then you can start the demo slides as usual.
+
+## Publishing
+
+When publishing the theme, non-JS files like `.vue` and `.ts` files can be published directly without compiling. Slidev will automatically compile them when using the theme.
+
+Themes should follow the following conventions:
+
+- Package name should start with `slidev-theme-`. For example, `slidev-theme-name` or `@scope/slidev-theme-name`
+- Add `"slidev-theme"` and `"slidev"` in the `keywords` field of your `package.json`
+
+Theme can be used locally without publishing to NPM. If your theme is only for personal use, you can simply use it as a local theme, or publish it as a private scoped package. However, it is recommended to publish it to the NPM registry if you want to share it with others.

package/index.md

@@ -0,0 +1,6 @@
+---
+layout: home
+markdownStyles: false
+---
+
+<LandingPage />

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@slidev/docs",
+  "type": "module",
+  "version": "51.6.2",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/antfu",
+  "homepage": "https://sli.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/slidevjs/slidev",
+    "directory": "docs"
+  },
+  "bugs": "https://github.com/slidevjs/slidev/issues",
+  "files": [
+    "**/*.md",
+    "!.vitepress/**"
+  ],
+  "devDependencies": {
+    "@antfu/utils": "^9.2.0",
+    "@iconify/json": "^2.2.338",
+    "@shikijs/vitepress-twoslash": "^3.4.2",
+    "@types/node": "^22.15.18",
+    "@unocss/reset": "^66.1.2",
+    "@vueuse/core": "^13.2.0",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^14.1.0",
+    "shiki": "^3.4.2",
+    "typeit": "8.1.0",
+    "typescript": "^5.8.3",
+    "unocss": "^66.1.2",
+    "unplugin-icons": "^22.1.0",
+    "unplugin-vue-components": "^28.5.0",
+    "vite-plugin-inspect": "^11.0.1",
+    "vitepress": "^2.0.0-alpha.5",
+    "vitepress-plugin-llms": "^1.1.4",
+    "vue": "^3.5.14",
+    "@slidev/parser": "51.6.2",
+    "@slidev/client": "51.6.2",
+    "@slidev/types": "51.6.2"
+  },
+  "scripts": {
+    "dev": "vitepress",
+    "build": "vitepress build",
+    "preview": "vitepress preview"
+  }
+}

package/resources/addon-gallery.md

@@ -0,0 +1,32 @@
+---
+aside: false
+---
+
+<script setup>
+import AddonGallery from '../.vitepress/theme/components/AddonGallery.vue'
+</script>
+
+# Addon Gallery
+
+Browse awesome addons available for Slidev here.
+
+Read more about <LinkInline link="guide/theme-addon#use-addon" /> to use them, and <LinkInline link="guide/write-addon" /> to create your own addon.
+
+## Official Addons
+
+<ClientOnly>
+  <AddonGallery collection="official"/>
+</ClientOnly>
+
+## Community Addons
+
+Here are the curated addons made by the community.
+
+<!-- Edit in ./docs/.vitepress/addons.ts -->
+<ClientOnly>
+  <AddonGallery collection="community"/>
+</ClientOnly>
+
+## More Addons
+
+Find all the [addons available on NPM](https://www.npmjs.com/search?q=keywords%3Aslidev-addon).

package/resources/covers.md

@@ -0,0 +1,16 @@
+# Curated Covers
+
+We curated a few cover images to demonstrate our starter template.
+
+![](/screenshots/covers.png)
+
+```yaml
+---
+# random image from the curated collection
+background: https://cover.sli.dev
+---
+```
+
+If you enjoy any of them, check out our [Unsplash collection](https://unsplash.com/collections/94734566/slidev) and find out their authors.
+
+[cover.sli.dev](https://cover.sli.dev) is hosted from [`slidevjs/slidev-covers`](https://github.com/slidevjs/slidev-covers).

package/resources/learning.md

@@ -0,0 +1,22 @@
+# Learning Resources
+
+## English
+
+### Videos
+
+- [Slidev - one of the best presentation software and it is free!](https://www.youtube.com/watch?v=oSgM6GoSwyY) - by [Federico Tartarini](https://www.youtube.com/@FedericoTartarini)
+
+### Articles
+
+- [Tips To Turn R Markdown Into Slidev Presentation](https://yutani.rbind.io/post/2021-06-05-tips-to-turn-r-markdown-into-slidev-presentation/) by Hiroaki Yutani
+
+## 中文
+
+- [Slidev：一个用Markdown写slides的神器](https://zhuanlan.zhihu.com/p/372729473) by [梦里风林](https://www.zhihu.com/people/meng-li-feng-lin)
+- [神器！这款开源项目可以让你使用 Markdown 来做 PPT！](https://zhuanlan.zhihu.com/p/377567327) by [Github掘金计划](https://www.zhihu.com/people/github-stars)
+
+## 日本語
+
+- [開発者のためのスライド作成ツール Slidev がすごい](https://zenn.dev/ryo_kawamata/articles/introduce-slidev) by [ryo_kawamata](https://zenn.dev/ryo_kawamata)
+- [Markdownでオシャレなスライドを作るSli.dev](https://qiita.com/e99h2121/items/a115f8865a0dc21bb462) by [Nobuko YAMADA](https://qiita.com/e99h2121)
+- [【Slidev 超入門】エンジニアだからこそ作れるつよつよスライドの作り方！](https://zenn.dev/takumaru/articles/3faa75c2f09493) by [takuma-ru](https://zenn.dev/takumaru)

package/resources/showcases.md

@@ -0,0 +1,10 @@
+---
+aside: false
+---
+
+# Showcases
+
+Talks / Presentations using Slidev.
+
+<!-- Edit in ./docs/.vitepress/showcases.ts -->
+<ShowCases />

package/resources/theme-gallery.md

@@ -0,0 +1,32 @@
+---
+aside: false
+---
+
+<script setup>
+import ThemeGallery from '../.vitepress/theme/components/ThemeGallery.vue'
+</script>
+
+# Theme Gallery
+
+Browse awesome themes available for Slidev here.
+
+Read more about <LinkInline link="guide/theme-addon#use-theme" /> to use them, and <LinkInline link="guide/write-theme" /> to create your own theme.
+
+## Official Themes {#official-themes}
+
+<ClientOnly>
+  <ThemeGallery collection="official"/>
+</ClientOnly>
+
+## Community Themes {#community-themes}
+
+Here are the curated themes made by the community.
+
+<!-- Edit in ./docs/.vitepress/themes.ts -->
+<ClientOnly>
+  <ThemeGallery collection="community"/>
+</ClientOnly>
+
+## More Themes {#more-themes}
+
+Find all the [themes available on NPM](https://www.npmjs.com/search?q=keywords%3Aslidev-theme).