@slidev/docs 51.6.2

package/guide/hosting.md

@@ -0,0 +1,220 @@
+---
+outline: deep
+---
+
+# Building and Hosting
+
+Slidev is designed to run as a web server when you are editing or presenting your slides. However, after the presentation, you may still want to share your **interactive** slides with others. This guide will show you how to build and host your slides.
+
+## Build as a SPA {#spa}
+
+You can build the slides into a static [Single-page application (SPA)](https://developer.mozilla.org/en-US/docs/Glossary/SPA) via the following command:
+
+```bash
+$ slidev build
+```
+
+By default, the generated files are placed in the `dist` folder. You can test the built version of you slides by running: `npx vite preview` or any other static server.
+
+### Base Path {#base}
+
+To deploy your slides under sub-routes, you need to pass the `--base` option. The `--base` path **must begin and end with a slash `/`**. For example:
+
+```bash
+$ slidev build --base /talks/my-cool-talk/
+```
+
+Refer to [Vite's documentation](https://vitejs.dev/guide/build.html#public-base-path) for more details.
+
+### Output directory {#output-directory}
+
+You can change the output directory using `--out`.
+
+```bash
+$ slidev build --out my-build-folder
+```
+
+### Multiple Builds {#multiple-builds}
+
+You can build multiple slide decks in one go by passing multiple markdown files as arguments:
+
+```bash
+$ slidev build slides1.md slides2.md
+```
+
+Or if your shell supports it, you can use a glob pattern:
+
+```bash
+$ slidev build *.md
+```
+
+In this case, each input file will generate a folder containing the build in the output directory.
+
+### Examples {#examples}
+
+Here are a few examples of the exported SPA:
+
+- [Demo Slides](https://sli.dev/demo/starter)
+- [Composable Vue](https://talks.antfu.me/2021/composable-vue) by [Anthony Fu](https://github.com/antfu)
+- More in [Showcases](../resources/showcases)
+
+### Options {#options}
+
+<LinkCard link="features/build-with-pdf" />
+<LinkCard link="features/bundle-remote-assets" />
+
+## Hosting {#hosting}
+
+We recommend using `npm init slidev@latest` to scaffold your project, which contains the necessary configuration files for hosting services out-of-the-box.
+
+### GitHub Pages {#github-pages}
+
+To deploy your slides on [GitHub Pages](https://pages.github.com/) via GitHub Actions, follow these steps:
+
+1. In your repository, go to `Settings` > `Pages`. Under `Build and deployment`, select `GitHub Actions`. (Do not choose `Deploy from a branch` and upload the `dist` directory, which is not recommended.)
+2. Create `.github/workflows/deploy.yml` with the following content to deploy your slides to GitHub Pages via GitHub Actions.
+
+::: details deploy.yml
+
+```yaml
+name: Deploy pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+
+      - name: Setup @antfu/ni
+        run: npm i -g @antfu/ni
+
+      - name: Install dependencies
+        run: nci
+
+      - name: Build
+        run: nr build --base /${{github.event.repository.name}}/
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+:::
+
+3. Commit and push the changes to your repository. The GitHub Actions workflow will automatically deploy your slides to GitHub Pages every time you push to the `main` branch.
+4. You can access your slides at `https://<username>.github.io/<repository-name>/`.
+
+### Netlify
+
+Create `netlify.toml` in your project root with the following content:
+
+::: details netlify.toml
+
+```toml
+[build]
+publish = 'dist'
+command = 'npm run build'
+
+[build.environment]
+NODE_VERSION = '20'
+
+[[redirects]]
+from = '/*'
+to = '/index.html'
+status = 200
+```
+
+:::
+
+Then go to your [Netlify dashboard](https://netlify.com/) and create a new site with the repository.
+
+### Vercel
+
+Create `vercel.json` in your project root with the following content:
+
+::: details vercel.json
+
+```json
+{
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
+```
+
+:::
+
+Then go to your [Vercel dashboard](https://vercel.com/) and create a new site with the repository.
+
+### Host on Docker {#docker}
+
+If you need a rapid way to run a presentation with containers, you can use the prebuilt [docker image](https://hub.docker.com/r/tangramor/slidev) maintained by [tangramor](https://github.com/tangramor), or build your own.
+
+::: details Use the Docker Image
+
+Just run the following command in your work folder:
+
+```bash
+docker run --name slidev --rm -it \
+    --user node \
+    -v ${PWD}:/slidev \
+    -p 3030:3030 \
+    -e NPM_MIRROR="https://registry.npmmirror.com" \
+    tangramor/slidev:latest
+```
+
+**_Note_**: You can use `NPM_MIRROR` to specify a npm mirror to speed up the installation process.
+
+If your work folder is empty, it will generate a template `slides.md` and other related files under your work folder, and launch the server on port `3030`.
+
+You can access your slides from `http://localhost:3030/`
+
+To create an Docker Image for your slides, you can use the following Dockerfile:
+
+```Dockerfile
+FROM tangramor/slidev:latest
+
+ADD . /slidev
+```
+
+Create the docker image: `docker build -t myslides .`
+
+And run the container: `docker run --name myslides --rm --user node -p 3030:3030 myslides`
+
+You can visit your slides at `http://localhost:3030/`
+
+:::

package/guide/index.md

@@ -0,0 +1,161 @@
+---
+outline: deep
+---
+
+# Getting Started
+
+Slidev <sup>(slide + dev, **/slaɪdɪv/**)</sup> is a web-based slides maker and presenter. It's designed for developers to focus on writing content in Markdown. With the power of web technologies like Vue, you are able to deliver pixel-perfect designs with interactive demos to your presentation.
+
+::: tip
+
+You can learn more about the rationale behind this project in <LinkInline link="guide/why" />.
+
+:::
+
+<!--
+- 📝 [**Markdown-based**](/guide/syntax) - focus on content and use your favorite editor
+- 🧑‍💻 [**Developer Friendly**](/guide/syntax#code-blocks) - built-in code highlighting, live coding, etc.
+- 🎨 [**Themable**](/resources/theme-gallery) - theme can be shared and used with npm packages
+- 🌈 [**Stylish**](/guide/syntax#embedded-styles) - on-demand utilities via [UnoCSS](https://github.com/unocss/unocss).
+- 🤹 [**Interactive**](/custom/directory-structure#components) - embedding Vue components seamlessly
+- 🎙 [**Presenter Mode**](/guide/ui#presenter-mode) - use another window, or even your phone to control your slides
+- 🎨 [**Drawing**](/features/drawing) - draw and annotate on your slides
+- 🧮 [**LaTeX**](/guide/syntax#latex) - built-in LaTeX math equations support
+- 📰 [**Diagrams**](/guide/syntax#diagrams) - creates diagrams using textual descriptions with [Mermaid.js](https://mermaid.js.org/)
+- 🌟 [**Icons**](/guide/syntax#icons) - access to icons from any icon set directly
+- 💻 [**Editor**](/guide/index#editor) - integrated editor, or the [VSCode extension](/features/vscode-extension)
+- 🎥 [**Recording**](/features/recording) - built-in recording and camera view
+- 📤 [**Portable**](/guide/exporting) - export into PDF, PNGs, or PPTX
+- ⚡️ [**Fast**](https://vitejs.dev) - instant reloading powered by [Vite](https://vitejs.dev)
+- 🛠 [**Hackable**](/custom/) - using Vite plugins, Vue components, or any npm packages
+-->
+
+<!-- <FeaturesAnimation /> -->
+
+## Create Slides
+
+### Try it Online
+
+Start Slidev right in your browser with StackBlitz: [sli.dev/new](https://sli.dev/new)
+
+### Create Locally
+
+> Requires [Node.js](https://nodejs.org) >= 18.0 installed.
+
+Run the following command to create a new Slidev project locally:
+
+::: code-group
+
+```bash [pnpm]
+# If you haven't installed pnpm
+npm i -g pnpm
+
+pnpm create slidev
+```
+
+```bash [npm]
+# Not recommended -
+# NPM will download the packages each time you create a new project,
+# which is slow and takes up a lot of space
+
+npm init slidev@latest
+```
+
+```bash [yarn]
+yarn create slidev
+```
+
+```bash [bun]
+bun create slidev
+```
+
+:::
+
+Follow the prompts to start your slides project. The slides content is in `slides.md`, which initially includes demos of most the Slidev features. For more information about the Markdown syntax, please check <LinkInline link="guide/syntax" />.
+
+:::: details Single file usage (not recommended)
+
+If you prefer to have a single Markdown file as your slides, you can install the Slidev CLI globally:
+
+::: code-group
+
+```bash [pnpm]
+pnpm i -g @slidev/cli
+```
+
+```bash [npm]
+npm i -g @slidev/cli
+```
+
+```bash [yarn]
+yarn global add @slidev/cli
+```
+
+```bash [bun]
+bun i -g @slidev/cli
+```
+
+:::
+
+Then, you can create and start a single file slides via:
+
+```bash
+slidev slides.md
+```
+
+::::
+
+## Basic Commands
+
+Slidev provides a set of commands in its CLI. Here are some common ones:
+
+- `slidev` - Start the dev server. See [the dev command](../builtin/cli#dev).
+- `slidev export` - Export the slides to PDF, PPTX, or PNGs. See <LinkInline link="guide/exporting" />.
+- `slidev build` - Build the slides as a static web application. See <LinkInline link="guide/hosting" />.
+- `slidev format` - Format the slides. See [the format command](../builtin/cli#format).
+- `slidev --help` - Show the help message
+
+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
+{
+  "scripts": {
+    "dev": "slidev --open",
+    "build": "slidev build",
+    "export": "slidev export"
+  }
+}
+```
+
+Then, you can simply run `npm run dev`, `npm run build`, and `npm run export`.
+
+For more information about the CLI, please check the [CLI guide](../builtin/cli).
+
+## Setup Your Editor {#editor}
+
+Since Slidev uses Markdown as the source entry, you can use any editor you prefer to create your slides. We also provide tools to help you edit you slides more conveniently:
+
+<LinkCard link="features/vscode-extension" />
+<LinkCard link="features/side-editor" />
+<LinkCard link="features/prettier-plugin" />
+
+## Join the Community
+
+It's recommended to join our official [Discord Server](https://chat.sli.dev/) to get help, share your slides, or discuss anything about Slidev.
+
+If you're encountering bugs, feel free to open an issue on [GitHub](https://github.com/slidevjs/slidev/issues/new/choose).
+
+## Tech Stack
+
+Slidev is made possible by combining these tools and technologies.
+
+- [Vite](https://vitejs.dev) - An extremely fast frontend tooling
+- [Vue 3](https://v3.vuejs.org/) powered [Markdown](https://daringfireball.net/projects/markdown/syntax) - Focus on the content while having the power of HTML and Vue components whenever needed
+- [UnoCSS](https://github.com/unocss/unocss) - On-demand utility-first CSS framework, style your slides at ease
+- [Shiki](https://github.com/shikijs/shiki), [Monaco Editor](https://github.com/Microsoft/monaco-editor) - First-class code snippets support with live coding capability
+- [RecordRTC](https://recordrtc.org) - Built-in recording and camera view
+- [VueUse](https://vueuse.org) family - [`@vueuse/core`](https://github.com/vueuse/vueuse), [`@vueuse/head`](https://github.com/vueuse/head), [`@vueuse/motion`](https://github.com/vueuse/motion), etc.
+- [Iconify](https://iconify.design/) - Iconsets collection.
+- [Drauu](https://github.com/antfu/drauu) - Drawing and annotations support
+- [KaTeX](https://katex.org/) - LaTeX math rendering.
+- [Mermaid](https://mermaid-js.github.io/mermaid) - Textual Diagrams.

package/guide/layout.md

@@ -0,0 +1,32 @@
+# Slide Layout
+
+Layouts in Slidev are used to define the structure for each slides. They are Vue components that wrap the content of the slides.
+
+## Using Layouts {#use}
+
+To use a layout, you can specify it in the frontmatter of the slide:
+
+```md
+---
+layout: quote
+---
+
+A quote from someone
+```
+
+By default, the layout of the first slide is `cover`, and the rest are `default`.
+
+The layouts are loaded in the following order, and the last one loaded will override the previous ones:
+
+1. default layouts. See [Built-in Layouts](../builtin/layouts).
+2. layouts provided by the theme
+3. layouts provided by the addons
+4. custom layouts in the `layouts` directory
+
+<SeeAlso :links="[
+  'features/slot-sugar',
+]" />
+
+## Writing Layouts {#write}
+
+<LinkCard link="guide/write-layout" />

package/guide/syntax.md

@@ -0,0 +1,179 @@
+---
+outline: deep
+---
+
+# Syntax Guide
+
+Slidev's slides are written as Markdown files, which are called **Slidev Markdown**s. A presentation has a Slidev Markdown as its entry, which is `./slides.md` by default, but you can change it by passing the file path as an argument to [the CLI commands](../builtin/cli).
+
+In a Slidev Markdown, not only [the basic Markdown features](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) can be used as usual, Slidev also provides additional features to enhance your slides. This section covers the syntax introduced by Slidev. Please make sure you know the basic Markdown syntax before reading this guide.
+
+## Slide Separators {#slide-separators}
+
+Use `---` padded with a new line to separate your slides.
+
+````md {5,15}
+# Title
+
+Hello, **Slidev**!
+
+---
+
+# Slide 2
+
+Use code blocks for highlighting:
+
+```ts
+console.log('Hello, World!')
+```
+
+---
+
+# Slide 3
+
+Use UnoCSS classes and Vue components to style and enrich your slides:
+
+<div class="p-3">
+  <Tweet id="..." />
+</div>
+````
+
+## Frontmatter & Headmatter {#frontmatter}
+
+At the beginning of each slide, you can add an optional [frontmatter](https://jekyllrb.com/docs/front-matter/) to configure the slide. The first frontmatter block is called **headmatter** and can configure the whole slide deck. The rest are **frontmatters** for individual slides. Texts in the headmatter or the frontmatter should be an object in [YAML](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started/) format. For example:
+
+<!-- eslint-skip -->
+
+```md {1-4,10-14,26-28}
+---
+theme: seriph
+title: Welcome to Slidev
+---
+
+# Slide 1
+
+The frontmatter of this slide is also the headmatter
+
+---
+layout: center
+background: /background-1.png
+class: text-white
+---
+
+# Slide 2
+
+A page with the layout `center` and a background image
+
+---
+
+# Slide 3
+
+A page without frontmatter
+
+---
+src: ./pages/4.md  # This slide only contains a frontmatter
+---
+
+---
+
+# Slide 5
+```
+
+Configurations you can set are described in the [Slides deck configurations](/custom/#headmatter) and [Per slide configurations](/custom/#frontmatter) sections.
+
+To make the headmatter more readable, you can install the VSCode extension:
+
+<LinkCard link="features/vscode-extension" />
+
+Also, there is another possible frontmatter format:
+
+<LinkCard link="features/block-frontmatter" />
+
+## Notes {#notes}
+
+You can also create presenter notes for each slide. They will show up in <LinkInline link="guide/ui#presenter-mode" /> for you to reference during presentations.
+
+The comment blocks at the end of each slide are treated as the note of the slide:
+
+```md {9,19-21}
+---
+layout: cover
+---
+
+# Slide 1
+
+This is the cover page.
+
+<!-- This is a **note** -->
+
+---
+
+# Slide 2
+
+<!-- This is NOT a note because it is not at the end of the slide -->
+
+The second page
+
+<!--
+This is _another_ note
+-->
+```
+
+Basic Markdown and HTML are also supported in notes and will be rendered.
+
+<SeeAlso :links="[
+  'features/click-marker',
+]" />
+
+## Code Blocks {#code-block}
+
+One big reason that led to the creation of Slidev was the need to perfectly display code in slides. Consequently, you can use Markdown-flavored code blocks to highlight your code.
+
+````md
+```ts
+console.log('Hello, World!')
+```
+````
+
+Slidev has [Shiki](https://github.com/shikijs/shiki) built in as the syntax highlighter. Refer to [Configure Shiki](/custom/config-highlighter) for more details.
+
+More about code blocks:
+
+<LinkCard link="features/code-block-line-numbers" />
+<LinkCard link="features/code-block-max-height" />
+<LinkCard link="features/line-highlighting" />
+<LinkCard link="features/monaco-editor" />
+<LinkCard link="features/monaco-run" />
+<LinkCard link="features/monaco-write" />
+<LinkCard link="features/shiki-magic-move" />
+<LinkCard link="features/twoslash" />
+<LinkCard link="features/import-snippet" />
+
+## LaTeX Blocks {#latex-block}
+
+Slidev supports LaTeX blocks for mathematical and chemical formulas:
+
+<LinkCard link="features/latex" />
+
+## Diagrams {#diagrams}
+
+Slidev supports [Mermaid](https://mermaid.js.org/) and [PlantUML](https://plantuml.com/) for creating diagrams from text:
+
+<LinkCard link="features/mermaid" />
+<LinkCard link="features/plantuml" />
+
+## MDC Syntax {#mdc-syntax}
+
+MDC Syntax is the easiest way to apply styles and classes to elements:
+
+<LinkCard link="features/mdc" />
+
+## Scoped CSS {#scoped-css}
+
+You can use scoped CSS to style your slides:
+
+<LinkCard link="features/slide-scope-style" />
+
+## Importing Slides {#importing-slides}
+
+<LinkCard link="features/importing-slides" />

package/guide/theme-addon.md

@@ -0,0 +1,62 @@
+# Theme and Addons
+
+A slides project can have one theme and multiple addons. All of them can provide styles, components, layouts, and other configs to your slides project.
+
+## Use a Theme {#use-theme}
+
+Changing the theme in Slidev is surprisingly easy. All you need to do is to add the `theme` option in your [headmatter](../custom/index#headmatter):
+
+```md
+---
+theme: seriph
+---
+
+# The first slide
+```
+
+You can find the list of official themes and community themes in the [Themes Gallery](../resources/theme-gallery).
+
+::: info Theme name convention
+
+- You can also pass a relative or absolute path to a local theme folder, like `../my-theme`
+- You can always use the full package name as the theme name
+- If the theme is [official](../resources/theme-gallery#official-themes) or is named like `slidev-theme-name`, you can omit the `slidev-theme-` prefix
+- For scoped packages like `@org/slidev-theme-name`, the full package name is required
+
+:::
+
+You can start the server and will be prompted to install the theme after a confirmation.
+
+<div class="language-md text-xs pl-6">
+<pre style="overflow: hidden; text-wrap: pretty;">
+<span class="token keyword">?</span> The theme <span class="token string">"@slidev/theme-seriph"</span> was not found in your project, do you want to install it now? › (Y/n)
+</pre>
+</div>
+
+or install the theme manually via:
+
+```bash
+$ npm install @slidev/theme-seriph
+```
+
+And that's all, enjoy the new theme! For more details about the usage, you can refer to the theme's README.
+
+<SeeAlso :links="[
+  'features/eject-theme',
+]" />
+
+## Use an Addon {#use-addon}
+
+Addons are similar to themes, but they are more flexible and can be used to add extra features to your slides project. You can add multiple addons to your project, and they can be used to add extra features to your slides project.
+
+To use an addon, you can add the `addons` option in your [headmatter](../custom/index#headmatter):
+
+```md
+---
+addons:
+  - excalidraw
+  - '@slidev/plugin-notes'
+---
+```
+
+You can find the list of official addons and community addons in the [Addons Gallery](../resources/addon-gallery).