Merge pull request #5 from slidevjs/sync-43ba9b51

docs(en): merge docs/main into docs-vn/main @ 43ba9b5

Author: bongudth

builtin/cli.md

@@ -0,0 +1,95 @@
+# Slidev CLI
+
+`@slidev/cli` exposes a binary called `slidev` that you can use to develop, build, and export your slides.
+
+## Prerequisites
+
+To use the CLI, you can either install `@slidev/cli` globally or install it locally in your Node.js project. If you created your project with `npm init slidev`, the CLI is already installed locally.
+
+::: warning
+Usually `npx slidev` is not supported because the package name is actually `@slidev/cli`.
+:::
+
+The CLI options of the commands obey the following conventions:
+
+- the value of the option can be passed after a space or a `=` character:
+
+  Example: `slidev --port 8080` is equivalent to `slidev --port=8080`
+
+- `true` can be omitted for boolean options:
+
+  Example: `slidev --open` is equivalent to `slidev --open true`
+
+::: info
+
+If you use npm, please don't forget to add `--` before the options to pass them to Slidev:
+
+```bash
+npm run slidev -- --remote --port 8080 --open
+```
+
+:::
+
+## `slidev [entry]` {#dev}
+
+Start a local server for Slidev.
+
+- `[entry]` (`string`, default: `slides.md`): path to the markdown file containing your slides.
+
+Options:
+
+- `--port`, `-p` (`number`, default: `3030`): port number.
+- `--open`, `-o` (`boolean`, default: `false`): open in the browser.
+- `--remote [password]` (`string`): listen to the public host and enable remote control, if a value is passed then the presenter mode is private and only accessible by passing the given password in the URL query `password` parameter.
+- `--bind` (`string`, default: `0.0.0.0`): specify which IP addresses the server should listen on in the remote mode.
+- `--log` (`'error', 'warn', 'info', 'silent'`, default: `'warn'`): Log level.
+- `--force`, `-f` (`boolean`, default: `false`): force the optimizer to ignore the cache and re-bundle.
+- `--theme`, `-t` (`string`): override theme.
+
+## `slidev build [entry]` {#build}
+
+Build a hostable SPA. See <LinkInline link="guide/hosting" /> for more details.
+
+- `[entry]` (`string`, default: `slides.md`): path to the slides markdown file.
+
+Options:
+
+- `--out`, `-o` (`string`, default: `dist`): output directory
+- `--base` (`string`, default: `/`): base URL (see https://vitejs.dev/config/shared-options.html#base)
+- `--download` (`boolean`, default: `false`): allow the download of the slides as a PDF inside the SPA
+- `--theme`, `-t` (`string`): override theme
+
+## `slidev export [...entry]` {#export}
+
+Export slides to PDF (or other format). See <LinkInline link="guide/exporting" /> for more details.
+
+- `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry.
+
+Options:
+
+- `--output` (`string`, default: use `exportFilename` (see https://sli.dev/custom/#frontmatter-configures) or use `[entry]-export`): path to the output.
+- `--format` (`'pdf', 'png', 'pptx', 'md'`, default: `'pdf'`): output format.
+- `--timeout` (`number`, default: `30000`): timeout for rendering the print page (see https://playwright.dev/docs/api/class-page#page-goto).
+- `--range` (`string`): page ranges to export (example: `'1,4-5,6'`).
+- `--dark` (`boolean`, default: `false`): export as dark theme.
+- `--with-clicks`, `-c` (`boolean`, default: `false`): export pages for every click animation (see https://sli.dev/guide/animations.html#click-animation).
+- `--theme`, `-t` (`string`): override theme.
+- `--omit-background` (`boolean`, default: `false`): remove the default browser background
+
+## `slidev format [entry]` {#format}
+
+Format the markdown file. Note that this won't format the content of the slides, only the organization of the markdown file.
+
+- `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry.
+
+## `slidev theme [subcommand]` {#theme}
+
+Theme-related operations.
+
+Subcommands:
+
+- `eject [entry]`: Eject the current theme into the local file system. See <LinkInline link="features/eject-theme" />.
+  - `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry.
+  - Options:
+    - `--dir` (`string`, default: `theme`): the output dir.
+    - `--theme`, `-t` (`string`): override theme.

components.d.ts

@@ -11,21 +11,11 @@ declare module 'vue' {
     AddonInfo: typeof import('./.vitepress/theme/components/AddonInfo.vue')['default']
     Arrow: typeof import('./node_modules/@slidev/client/builtin/Arrow.vue')['default']
     AutoFitText: typeof import('./node_modules/@slidev/client/builtin/AutoFitText.vue')['default']
-    'Carbon:chevronLeft': typeof import('~icons/carbon/chevron-left')['default']
-    'Carbon:chevronRight': typeof import('~icons/carbon/chevron-right')['default']
-    'Carbon:close': typeof import('~icons/carbon/close')['default']
-    'Carbon:filterRemove': typeof import('~icons/carbon/filter-remove')['default']
-    'Carbon:logoGithub': typeof import('~icons/carbon/logo-github')['default']
-    'Carbon:logoTwitter': typeof import('~icons/carbon/logo-twitter')['default']
-    'Carbon:presentationFile': typeof import('~icons/carbon/presentation-file')['default']
-    'Carbon:reset': typeof import('~icons/carbon/reset')['default']
-    'Carbon:search': typeof import('~icons/carbon/search')['default']
-    'Carbon:tag': typeof import('~icons/carbon/tag')['default']
-    'Carbon:video': typeof import('~icons/carbon/video')['default']
     CarbonApps: typeof import('~icons/carbon/apps')['default']
     CarbonArrowLeft: typeof import('~icons/carbon/arrow-left')['default']
     CarbonArrowRight: typeof import('~icons/carbon/arrow-right')['default']
     CarbonBadge: typeof import('~icons/carbon/badge')['default']
+    CarbonDocumentPdf: typeof import('~icons/carbon/document-pdf')['default']
     CarbonDownload: typeof import('~icons/carbon/download')['default']
     CarbonEdit: typeof import('~icons/carbon/edit')['default']
     CarbonInformation: typeof import('~icons/carbon/information')['default']
@@ -36,6 +26,7 @@ declare module 'vue' {
     CarbonPen: typeof import('~icons/carbon/pen')['default']
     CarbonSettingsAdjust: typeof import('~icons/carbon/settings-adjust')['default']
     CarbonSun: typeof import('~icons/carbon/sun')['default']
+    CarbonTextAnnotationToggle: typeof import('~icons/carbon/text-annotation-toggle')['default']
     CarbonUserAvatar: typeof import('~icons/carbon/user-avatar')['default']
     CarbonUserSpeaker: typeof import('~icons/carbon/user-speaker')['default']
     CarbonVideo: typeof import('~icons/carbon/video')['default']

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.
+:::

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.

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 [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` | `none`
+- Default: `google`
+
+Currently, only Google Fonts is 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
+---
+```