feat: add CLI option to allow transparent pngs (#1797)

Co-authored-by: mo91dev <>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: _Kerman <kermanx@qq.com>

docs/builtin/cli.md

@@ -74,6 +74,7 @@ Options:
 - `--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}
 

docs/guide/exporting.md

@@ -178,3 +178,21 @@ You can generate the PDF outline by passing the `--with-toc` option:
 ```bash
 $ slidev export --with-toc
 ```
+
+### Omit Background
+
+When exporting to PNGs, you can remove the default browser background by passing `--omit-background`:
+
+```bash
+$ slidev export --omit-background
+```
+
+The default browser background is the white background visible on all browser windows and is different than other backgrounds applied throughout the application using CSS styling. [See Playwright docs](https://playwright.dev/docs/api/class-page#page-screenshot-option-omit-background). You will then need to apply additional CSS styling to the application to reveal the transparency.
+
+Here is a basic example that covers all backgrounds in the application:
+
+```css
+* {
+  background: transparent !important;
+}
+```

packages/slidev/node/cli.ts

@@ -603,6 +603,10 @@ function exportOptions<T>(args: Argv<T>) {
       type: 'number',
       describe: 'scale factor for image export',
     })
+    .option('omit-background', {
+      type: 'boolean',
+      describe: 'export png pages without the default browser background',
+    })
 }
 
 function printInfo(

packages/slidev/node/commands/export.ts

@@ -37,6 +37,7 @@ export interface ExportOptions {
    */
   perSlide?: boolean
   scale?: number
+  omitBackground?: boolean
 }
 
 interface ExportPngResult {
@@ -183,6 +184,7 @@ export async function exportSlides({
   perSlide = false,
   scale = 1,
   waitUntil,
+  omitBackground = false,
 }: ExportOptions) {
   const pages: number[] = parseRangeString(total, range)
 
@@ -402,7 +404,9 @@ export async function exportSlides({
       progress.update(i + 1)
       const id = (await slideContainers.nth(i).getAttribute('id')) || ''
       const slideNo = +id.split('-')[0]
-      const buffer = await slideContainers.nth(i).screenshot()
+      const buffer = await slideContainers.nth(i).screenshot({
+        omitBackground,
+      })
       result.push({ slideIndex: slideNo - 1, buffer })
       if (writeToDisk)
         await fs.writeFile(path.join(output, `${withClicks ? id : slideNo}.png`), buffer)
@@ -414,7 +418,9 @@ export async function exportSlides({
     const result: ExportPngResult[] = []
     const genScreenshot = async (no: number, clicks?: string) => {
       await go(no, clicks)
-      const buffer = await page.screenshot()
+      const buffer = await page.screenshot({
+        omitBackground,
+      })
       result.push({ slideIndex: no - 1, buffer })
       if (writeToDisk) {
         await fs.writeFile(
@@ -569,6 +575,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
       executablePath: args['executable-path'],
       withToc: args['with-toc'],
       perSlide: args['per-slide'],
+      omitBackground: args['omit-background'],
     }),
   }
   const {
@@ -585,6 +592,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
     withToc,
     perSlide,
     scale,
+    omitBackground,
   } = config
   outFilename = output || options.data.config.exportFilename || outFilename || `${path.basename(entry, '.md')}-export`
   if (outDir)
@@ -607,6 +615,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
     withToc: withToc || false,
     perSlide: perSlide || false,
     scale: scale || 2,
+    omitBackground: omitBackground ?? false,
   }
 }
 

packages/types/src/cli.ts

@@ -16,6 +16,7 @@ export interface ExportArgs extends CommonArgs {
   'with-toc'?: boolean
   'per-slide'?: boolean
   'scale'?: number
+  'omit-background'?: boolean
 }
 
 export interface BuildArgs extends ExportArgs {