From 1863494ab4e60e84d78563a6c30f1667e390057e Mon Sep 17 00:00:00 2001
From: Oliver-Tobias Ripka <contact@oripka.de>
Date: Sun, 7 Sep 2025 15:49:07 +0200
Subject: [PATCH 1/3] feat: handout

---
 demo/starter/handout-bottom.vue               |  41 +++++
 demo/starter/handout-cover.vue                |  51 ++++++
 packages/client/composables/useNav.ts         |   2 +-
 packages/client/composables/usePrintStyles.ts |   6 +-
 .../internals/PrintContainerHandout.vue       |  58 +++++++
 packages/client/internals/PrintHandout.vue    | 160 ++++++++++++++++++
 packages/client/pages/cover/print.vue         |  62 +++++++
 packages/client/pages/handout/print.vue       | 114 +++++++++++++
 packages/client/setup/routes.ts               |  21 +++
 packages/slidev/node/cli.ts                   |  10 ++
 packages/slidev/node/commands/export.ts       | 101 ++++++++++-
 .../slidev/node/virtual/handout-components.ts |  34 ++++
 packages/slidev/node/virtual/index.ts         |   3 +
 packages/types/client.d.ts                    |  14 ++
 packages/types/src/cli.ts                     |   2 +
 15 files changed, 670 insertions(+), 9 deletions(-)
 create mode 100644 demo/starter/handout-bottom.vue
 create mode 100644 demo/starter/handout-cover.vue
 create mode 100644 packages/client/internals/PrintContainerHandout.vue
 create mode 100644 packages/client/internals/PrintHandout.vue
 create mode 100644 packages/client/pages/cover/print.vue
 create mode 100644 packages/client/pages/handout/print.vue
 create mode 100644 packages/slidev/node/virtual/handout-components.ts

diff --git a/demo/starter/handout-bottom.vue b/demo/starter/handout-bottom.vue
new file mode 100644
index 0000000000..74c358c632
--- /dev/null
+++ b/demo/starter/handout-bottom.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+defineProps<{ pageNumber: number }>()
+// A footer layout that relies on the parent handout container for the full-width
+// top rule and page number placement. Avoid absolute positioning so the
+// container can reserve space and prevent overlaps.
+const year = new Date().getFullYear()
+// Replace these with your flavor system if needed
+const company = 'Slidev'
+const rightText = 'Presentation slides for developers'
+</script>
+
+<template>
+  <div class="handout-footer">
+    <div class="handout-row">
+      <div class="left">
+        © {{ year }} {{ company }}
+      </div>
+      <div class="right">
+        {{ rightText }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.handout-footer {
+  width: 100%;
+}
+.handout-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  font-size: 11px;
+  line-height: 1.2;
+  padding-top: 3mm; /* space below the rule drawn by container */
+}
+.left,
+.right {
+  white-space: nowrap;
+}
+</style>
diff --git a/demo/starter/handout-cover.vue b/demo/starter/handout-cover.vue
new file mode 100644
index 0000000000..3c5728d3e8
--- /dev/null
+++ b/demo/starter/handout-cover.vue
@@ -0,0 +1,51 @@
+<template>
+  <div>
+    <div class="break-after-page">
+      <span class="font-bold text-xl border-b-4 border-r-4 px-1 py-1 border-gray-800 ">
+        SLIDEV
+      </span>
+      <div class="h-56" />
+      <div class="max-w-md w-full mx-auto">
+        <div class="w-120 mx-auto font-bold flex flex-wrap gap-4">
+          <h1 class="text-5xl font-bold border-b-4 border-gray-800">
+            Welcome to Slidev
+          </h1>
+          v1.0
+        </div>
+        <div class="h-32" />
+        <div class="text-2xl font-bold mx-auto w-120 text-right">
+          Slidev Starter Template
+        </div>
+      </div>
+    </div>
+    <div class="break-after-page mt-68 mx-8 ">
+      <div class="font-bold text-xl mt-8">
+        COPYRIGHT
+      </div>
+      <div class="flex flex-row gap-4 mt-4 align-center items-center">
+        © {{ new Date().getFullYear().toString() }} Slidev.
+      </div>
+      <p class="mt-4">
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+      </p>
+      <p class="mt-4">
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+      </p>
+      <p class="mt-4">
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFMERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+      </p>
+    </div>
+  </div>
+</template>
diff --git a/packages/client/composables/useNav.ts b/packages/client/composables/useNav.ts
index e1500c42a4..5f2400ebbd 100644
--- a/packages/client/composables/useNav.ts
+++ b/packages/client/composables/useNav.ts
@@ -280,7 +280,7 @@ const useNavState = createSharedComposable((): SlidevContextNavState => {
     router?.currentRoute?.value?.query
     return new URLSearchParams(location.search)
   })
-  const isPrintMode = computed(() => query.value.has('print') || currentRoute.name === 'export')
+  const isPrintMode = computed(() => query.value.has('print') || currentRoute.name === 'export' || currentRoute.name === 'handout' || currentRoute.name === 'cover')
   const isPrintWithClicks = ref(query.value.get('print') === 'clicks')
   const isEmbedded = computed(() => query.value.has('embedded'))
   const isPlaying = computed(() => currentRoute.name === 'play')
diff --git a/packages/client/composables/usePrintStyles.ts b/packages/client/composables/usePrintStyles.ts
index eb05058801..a8693c8ee8 100644
--- a/packages/client/composables/usePrintStyles.ts
+++ b/packages/client/composables/usePrintStyles.ts
@@ -1,12 +1,16 @@
 import { useStyleTag } from '@vueuse/core'
 import { computed } from 'vue'
+import { useRoute } from 'vue-router'
 import { slideHeight, slideWidth } from '../env'
 import { useNav } from './useNav'
 
 export function usePrintStyles() {
   const { isPrintMode } = useNav()
+  const route = useRoute()
 
-  useStyleTag(computed(() => isPrintMode.value
+  // Only inject slide-sized @page for the default print/export view.
+  // Handout and cover have their own A4 page sizing and should not be overridden.
+  useStyleTag(computed(() => (isPrintMode.value && !['handout', 'cover'].includes((route.name as string) || ''))
     ? `
 @page {
   size: ${slideWidth.value}px ${slideHeight.value}px;
diff --git a/packages/client/internals/PrintContainerHandout.vue b/packages/client/internals/PrintContainerHandout.vue
new file mode 100644
index 0000000000..a80cc78349
--- /dev/null
+++ b/packages/client/internals/PrintContainerHandout.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { provideLocal } from '@vueuse/core'
+import { computed } from 'vue'
+import { useNav } from '../composables/useNav'
+import { injectionSlideScale } from '../constants'
+import { configs, slideAspect, slideWidth } from '../env'
+import PrintHandout from './PrintHandout.vue'
+
+const props = defineProps<{
+  width: number
+  pageOffset?: number
+}>()
+
+const { slides, printRange } = useNav()
+
+const width = computed(() => props.width)
+const height = computed(() => props.width / slideAspect.value)
+const screenAspect = computed(() => width.value / height.value)
+
+const scale = computed(() => {
+  if (screenAspect.value < slideAspect.value)
+    return width.value / slideWidth.value
+  return (height.value * slideAspect.value) / slideWidth.value
+})
+
+const className = computed(() => ({
+  'select-none': !configs.selectable,
+}))
+
+provideLocal(injectionSlideScale, scale)
+</script>
+
+<template>
+  <div id="print-container" :class="className">
+    <div id="print-content">
+      <PrintHandout
+        v-for="no of printRange"
+        :key="no"
+        :route="slides[no - 1]"
+        :index="no - 1"
+        :page-offset="props.pageOffset ?? 0"
+      />
+    </div>
+  </div>
+</template>
+
+<style lang="postcss">
+#print-content {
+  @apply bg-main;
+}
+.print-slide-container {
+  @apply relative overflow-hidden break-after-page translate-0;
+}
+/* Ensure printed background is white regardless of theme */
+html.print #print-content {
+  background: #ffffff !important;
+}
+</style>
diff --git a/packages/client/internals/PrintHandout.vue b/packages/client/internals/PrintHandout.vue
new file mode 100644
index 0000000000..c10932e866
--- /dev/null
+++ b/packages/client/internals/PrintHandout.vue
@@ -0,0 +1,160 @@
+<script setup lang="ts">
+import type { SlideRoute } from '@slidev/types'
+import HandoutBottom from '#slidev/global-components/handout-bottom'
+import { computed } from 'vue'
+import { slideHeight, slideWidth } from '../env'
+import NoteDisplay from './NoteDisplay.vue'
+import PrintSlide from './PrintSlide.vue'
+
+const props = defineProps<{
+  route: SlideRoute
+  index: number
+  pageOffset?: number
+}>()
+const route = computed(() => props.route)
+const pageOffset = computed(() => props.pageOffset ?? 0)
+
+// Use fixed A4 dimensions in CSS pixels (96 DPI) to avoid relying on
+// runtime viewport sizes which can skew scaling during headless export
+const PAGE_WIDTH_PX = Math.round(210 / 25.4 * 96)
+const PAGE_HEIGHT_PX = Math.round(297 / 25.4 * 96)
+const pageWidth = computed(() => PAGE_WIDTH_PX)
+const pageHeight = computed(() => PAGE_HEIGHT_PX)
+
+// Target layout: slide ~50% height, notes the rest, footer pinned
+const SLIDE_PORTION = 0.5
+const PX_PER_MM = 96 / 25.4
+// Inner paddings of the page box
+const PAGE_PAD_SIDE_MM = 12
+const PAGE_PAD_TOP_MM = 10
+const PAGE_PAD_BOTTOM_MM = 10
+// Extra margins around the slide area
+const SLIDE_SIDE_MARGIN_MM = 6
+const SLIDE_TOP_MARGIN_MM = 4
+
+// Constrain slide scale by width and by allowed height portion with top/side margins
+const scale = computed(() => {
+  const innerWidth = pageWidth.value - 2 * PAGE_PAD_SIDE_MM * PX_PER_MM
+  const innerHeight = pageHeight.value - (PAGE_PAD_TOP_MM + PAGE_PAD_BOTTOM_MM) * PX_PER_MM
+  const byWidth = (innerWidth - 2 * SLIDE_SIDE_MARGIN_MM * PX_PER_MM) / slideWidth.value
+  const byHeight = ((innerHeight * SLIDE_PORTION) - (SLIDE_TOP_MARGIN_MM * PX_PER_MM)) / slideHeight.value
+  const s = Math.min(1, byWidth, byHeight)
+  return Math.max(0, s - 0.006)
+})
+
+const slideHeightScaled = computed(() => slideHeight.value * scale.value)
+const slideAreaStyle = computed(() => ({
+  height: `${slideHeightScaled.value}px`,
+  padding: `${SLIDE_TOP_MARGIN_MM}mm ${SLIDE_SIDE_MARGIN_MM}mm 0`,
+}))
+</script>
+
+<template>
+  <div class="break-after-page page">
+    <div class="slide-area" :style="slideAreaStyle">
+      <div class="slide-scale-wrap" :style="{ width: `${slideWidth}px`, height: `${slideHeight}px`, transform: `scale(${scale})` }">
+        <PrintSlide :route="route" />
+      </div>
+    </div>
+    <div class="notes-area">
+      <NoteDisplay
+        v-if="route.meta?.slide!.noteHTML"
+        :note-html="route.meta?.slide!.noteHTML"
+        class="w-full mx-auto px-4 handout-notes"
+      />
+    </div>
+    <div class="footer-area">
+      <div class="footer-bleed">
+        <HandoutBottom :page-number="index + 1 + pageOffset" :page-offset="pageOffset" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* One handout page per printed page, sized to A4 with internal padding */
+.page {
+  display: flex;
+  flex-direction: column;
+  width: 210mm;
+  min-height: 297mm;
+  margin: 0 auto;
+  padding: 10mm 12mm 4mm; /* top, sides, bottom */
+
+  box-sizing: border-box;
+  break-after: page;
+  page-break-after: always; /* Chromium fallback */
+  break-inside: avoid-page;
+}
+.slide-area {
+  flex: 0 0 auto;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+}
+.slide-area {
+  /* Allow slide borders/shadows to render fully */
+  overflow: visible;
+  margin-bottom: 4mm;
+}
+.slide-scale-wrap {
+  transform-origin: top center;
+  margin: 0 auto;
+}
+.slide-scale-wrap :deep(.print-slide-container) {
+  break-after: auto;
+  /* Thin dark gray border around each slide in handout */
+  border: 1px solid rgba(0, 0, 0, 0.6);
+  border-radius: 2px;
+}
+.notes-area {
+  flex: 1 1 auto;
+  overflow: hidden;
+  display: flex;
+  /* add a bit more top spacing above notes */
+  padding: 8mm 3mm 12mm;
+}
+.handout-notes {
+  margin: 0 auto;
+  max-width: none;
+}
+.footer-area {
+  position: relative;
+  display: flex;
+  align-items: flex-end;
+  gap: 6mm;
+  flex: 0 0 auto;
+  min-height: 14mm;
+}
+/* full-width top rule across footer */
+.footer-area::before {
+  content: '';
+  position: absolute;
+  left: -12mm;
+  right: -12mm;
+  top: 0;
+  height: 1px;
+  background: #222;
+  opacity: 0.9;
+}
+.footer-bleed {
+  flex: 1 1 auto;
+  position: relative;
+  margin: 0;
+  overflow: visible;
+  padding-top: 2mm;
+}
+.footer-bleed :deep(*) {
+  max-width: 100% !important;
+  margin-left: 0 !important;
+  margin-right: 0 !important;
+  border-top-width: 0 !important;
+}
+.page-num {
+  flex: 0 0 auto;
+  font-size: 11px;
+  text-align: right;
+  padding-bottom: 1mm;
+  z-index: 1;
+}
+</style>
diff --git a/packages/client/pages/cover/print.vue b/packages/client/pages/cover/print.vue
new file mode 100644
index 0000000000..f41a17d22a
--- /dev/null
+++ b/packages/client/pages/cover/print.vue
@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import HandoutCover from '#slidev/global-components/handout-cover'
+import { watchEffect } from 'vue'
+import { useNav } from '../../composables/useNav'
+import { themeVars } from '../../env'
+
+const { isPrintMode } = useNav()
+
+watchEffect(() => {
+  const html = document.body.parentNode as HTMLElement
+  if (isPrintMode.value)
+    html.classList.add('print')
+  else
+    html.classList.remove('print')
+})
+</script>
+
+<template>
+  <div id="page-root" class="grid grid-cols-[1fr_max-content]" :style="themeVars">
+    <HandoutCover />
+  </div>
+</template>
+
+<style>
+html.print,
+html.print body,
+html.print #app {
+  height: auto;
+  overflow: auto;
+}
+
+html.print #page-root {
+  height: auto;
+  overflow: hidden;
+}
+
+html.print * {
+  -webkit-print-color-adjust: exact;
+}
+
+html.print {
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+html.print body {
+  margin: 0 auto;
+  border: 0;
+  padding: 0;
+  float: none;
+  overflow: visible;
+}
+
+@page {
+  size: A4;
+  margin-top: 1cm;
+  margin-bottom: 1cm;
+  margin-left: 1.5cm;
+  margin-right: 1.5cm;
+}
+</style>
diff --git a/packages/client/pages/handout/print.vue b/packages/client/pages/handout/print.vue
new file mode 100644
index 0000000000..e800f9ceb8
--- /dev/null
+++ b/packages/client/pages/handout/print.vue
@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import HandoutCover from '#slidev/global-components/handout-cover'
+import { useElementSize } from '@vueuse/core'
+import { computed, nextTick, onMounted, ref, watchEffect } from 'vue'
+import { useRoute } from 'vue-router'
+import { useNav } from '../../composables/useNav'
+import { themeVars } from '../../env'
+import PrintContainerHandout from '../../internals/PrintContainerHandout.vue'
+import { windowSize } from '../../state'
+
+const { isPrintMode } = useNav()
+
+const root = ref<HTMLElement | null>(null)
+const { width: rootWidth } = useElementSize(root)
+const route = useRoute()
+const includeCover = computed(() => route.query.cover != null)
+const coverRoot = ref<HTMLElement | null>(null)
+const pageOffset = ref(0)
+
+watchEffect(() => {
+  const html = document.body.parentNode as HTMLElement
+  if (isPrintMode.value)
+    html.classList.add('print')
+  else
+    html.classList.remove('print')
+})
+
+function recountCoverPages() {
+  if (!includeCover.value) {
+    pageOffset.value = 0
+    return
+  }
+  const el = coverRoot.value
+  if (!el) {
+    pageOffset.value = 1
+    return
+  }
+  // Heuristic: count elements intended to force page breaks.
+  // UnoCSS utility `break-after-page` is commonly used.
+  // If none found, assume a single-page cover.
+  const blocks = el.querySelectorAll('.break-after-page')
+  pageOffset.value = Math.max(1, blocks.length)
+}
+
+onMounted(async () => {
+  await nextTick()
+  recountCoverPages()
+})
+
+watchEffect(() => {
+  // Recount when toggling cover or when printing state changes
+  if (isPrintMode.value)
+    recountCoverPages()
+})
+</script>
+
+<template>
+  <div id="page-root" ref="root" :style="themeVars">
+    <!-- Optional cover block(s) when ?cover is present -->
+    <div v-if="includeCover" ref="coverRoot">
+      <HandoutCover />
+    </div>
+    <PrintContainerHandout
+      class="w-full h-full"
+      :width="rootWidth || windowSize.width.value"
+      :page-offset="pageOffset"
+    />
+  </div>
+</template>
+
+<style>
+html.print,
+html.print body,
+html.print #app {
+  height: auto;
+  overflow: auto;
+}
+/* Force white paper background in print */
+html.print,
+html.print body {
+  background: #ffffff !important;
+  color-scheme: light;
+}
+html.print #page-root {
+  height: auto;
+  /* Allow content to extend across multiple printed pages */
+  overflow: visible;
+}
+html.print * {
+  -webkit-print-color-adjust: exact;
+}
+html.print {
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+html.print body {
+  margin: 0 auto;
+  border: 0;
+  padding: 0;
+  float: none;
+  overflow: visible;
+}
+
+/* Cover content may contain its own break-after-page blocks to form pages */
+
+@page {
+  size: A4;
+  margin-top: 0cm;
+  margin-bottom: 0cm;
+  margin-left: 0cm;
+  margin-right: 0cm;
+}
+</style>
diff --git a/packages/client/setup/routes.ts b/packages/client/setup/routes.ts
index f7cc47f127..85f1e8dbb3 100644
--- a/packages/client/setup/routes.ts
+++ b/packages/client/setup/routes.ts
@@ -68,6 +68,7 @@ export default function setupRoutes() {
     )
   }
 
+  // Enable the browser exporter UI only when configured
   if (__SLIDEV_FEATURE_BROWSER_EXPORTER__) {
     routes.push(
       {
@@ -79,6 +80,26 @@ export default function setupRoutes() {
     )
   }
 
+  // Handout/Cover print routes are needed for both the browser exporter
+  // and the CLI exporter (print mode). Make them available when either
+  // feature is enabled so Playwright can navigate to them during CLI export.
+  if (__SLIDEV_FEATURE_BROWSER_EXPORTER__ || __SLIDEV_FEATURE_PRINT__) {
+    routes.push(
+      {
+        name: 'handout',
+        path: '/handout',
+        component: () => import('../pages/handout/print.vue'),
+        beforeEnter: passwordGuard,
+      },
+      {
+        name: 'cover',
+        path: '/cover',
+        component: () => import('../pages/cover/print.vue'),
+        beforeEnter: passwordGuard,
+      },
+    )
+  }
+
   routes.push(
     {
       name: 'play',
diff --git a/packages/slidev/node/cli.ts b/packages/slidev/node/cli.ts
index 0010a15818..4c6bbc34fe 100644
--- a/packages/slidev/node/cli.ts
+++ b/packages/slidev/node/cli.ts
@@ -39,6 +39,8 @@ const CONFIG_RESTART_FIELDS: (keyof SlidevConfig)[] = [
 const FILES_CREATE_RESTART = [
   'global-bottom.vue',
   'global-top.vue',
+  'handout-bottom.vue',
+  'handout-cover.vue',
   'uno.config.js',
   'uno.config.ts',
   'unocss.config.js',
@@ -584,6 +586,14 @@ function exportOptions<T>(args: Argv<T>) {
       type: 'string',
       describe: 'path to the output',
     })
+    .option('handout', {
+      type: 'boolean',
+      describe: 'export handout PDF (A4, one page per slide with notes and header/footer) to a separate file',
+    })
+    .option('cover', {
+      type: 'boolean',
+      describe: 'prepend a handout cover page if available (requires handout-cover.vue)',
+    })
     .option('format', {
       type: 'string',
       choices: ['pdf', 'png', 'pptx', 'md'],
diff --git a/packages/slidev/node/commands/export.ts b/packages/slidev/node/commands/export.ts
index 364c393fb8..e6a97693af 100644
--- a/packages/slidev/node/commands/export.ts
+++ b/packages/slidev/node/commands/export.ts
@@ -21,6 +21,8 @@ export interface ExportOptions {
   base?: string
   format?: 'pdf' | 'png' | 'pptx' | 'md'
   output?: string
+  handout?: boolean
+  cover?: boolean
   timeout?: number
   wait?: number
   waitUntil: 'networkidle' | 'load' | 'domcontentloaded' | undefined
@@ -139,7 +141,8 @@ export async function exportNotes({
 
   await page.goto(`http://localhost:${port}${base}presenter/print`, { waitUntil: 'networkidle', timeout })
   await page.waitForLoadState('networkidle')
-  await page.emulateMedia({ media: 'screen' })
+  // Use print media so @page rules (e.g. A4) apply
+  await page.emulateMedia({ media: 'print' })
 
   if (wait)
     await page.waitForTimeout(wait)
@@ -168,6 +171,8 @@ export async function exportSlides({
   range,
   format = 'pdf',
   output = 'slides',
+  handout = false,
+  cover = false,
   slides,
   base = '/',
   timeout = 30000,
@@ -190,18 +195,95 @@ export async function exportSlides({
   const browser = await chromium.launch({
     executablePath,
   })
+  // Use a sane, stable viewport for handout printing to avoid extremely tall pages
+  // that can cause Chromium to render black/blank pages when printing.
+  // For regular slide export, keep the original large viewport behavior.
+  const A4_WIDTH_PX = Math.round(210 / 25.4 * 96)
+  const A4_HEIGHT_PX = Math.round(297 / 25.4 * 96)
   const context = await browser.newContext({
-    viewport: {
-      width,
-      // Calculate height for every slides to be in the viewport to trigger the rendering of iframes (twitter, youtube...)
-      height: perSlide ? height : height * pages.length,
-    },
-    deviceScaleFactor: scale,
+    viewport: handout
+      ? { width: A4_WIDTH_PX, height: A4_HEIGHT_PX }
+      : {
+          width,
+          // Calculate height for every slides to be in the viewport to trigger the rendering of iframes (twitter, youtube...)
+          height: perSlide ? height : height * pages.length,
+        },
+    // Keep device scale modest for handout to reduce rasterization artifacts
+    deviceScaleFactor: handout ? 1 : scale,
   })
   const page = await context.newPage()
   const progress = createSlidevProgress(!perSlide)
   progress.start(pages.length)
 
+  // Simple handout export mode: directly print the handout route
+  if (handout) {
+    if (!output.endsWith('.pdf'))
+      output = `${output}.pdf`
+    const baseName = output.replace(/\.pdf$/, '')
+    const handoutOut = `${baseName}-handout.pdf`
+    // Build query string, optionally including cover
+    const qs = new URLSearchParams()
+    qs.set('print', 'true')
+    if (range)
+      qs.set('range', range)
+    if (cover)
+      qs.set('cover', 'true')
+    const handoutQuery = `?${qs.toString()}`
+    const handoutPath = routerMode === 'hash'
+      ? `http://localhost:${port}${base}${handoutQuery}#/handout`
+      : `http://localhost:${port}${base}handout${handoutQuery}`
+    // Avoid hanging on networkidle due to dev server websockets; prefer 'load'
+    const gotoWaitUntil = (waitUntil === 'networkidle' || !waitUntil) ? 'load' : waitUntil
+    await page.goto(handoutPath, { waitUntil: gotoWaitUntil, timeout })
+    if (gotoWaitUntil)
+      await page.waitForLoadState(gotoWaitUntil)
+    // For handouts, use print media and a light color scheme to avoid dark backgrounds
+    await page.emulateMedia({ colorScheme: 'light', media: 'print' })
+    // Ensure the app has switched to print mode (adds `html.print`)
+    try {
+      await page.waitForSelector('html.print', { state: 'attached', timeout: 5000 })
+    }
+    catch {}
+    // Wait until the handout pages are rendered (best-effort, non-blocking)
+    try {
+      // Limit how long we wait for initial container
+      await page.waitForSelector('#print-content', { state: 'attached', timeout: Math.min(timeout, 10000) })
+
+      // Wait briefly for page containers to appear and stabilize in count
+      const maxWait = 5000
+      const start = Date.now()
+      let lastCount = -1
+      while (Date.now() - start < maxWait) {
+        const cnt = await page.locator('.page').count()
+        if (cnt > 0 && cnt === lastCount)
+          break
+        lastCount = cnt
+        await page.waitForTimeout(200)
+      }
+
+      // Do not block on slide loading indicators; hide them if present
+      await page.locator('.slidev-slide-loading').evaluateAll((nodes) => {
+        nodes.forEach((n) => {
+          (n as HTMLElement).style.display = 'none'
+        })
+      }).catch(() => {})
+    }
+    catch {}
+    if (wait)
+      await page.waitForTimeout(wait)
+    await page.pdf({
+      format: 'A4',
+      path: handoutOut,
+      margin: { left: 0, top: 0, right: 0, bottom: 0 },
+      printBackground: true,
+      preferCSSPageSize: true,
+    })
+    progress.stop()
+    browser.close()
+    const relativeOutput = slash(relative('.', handoutOut))
+    return relativeOutput.startsWith('.') ? relativeOutput : `./${relativeOutput}`
+  }
+
   if (format === 'pdf') {
     await genPagePdf()
   }
@@ -469,6 +551,7 @@ export async function exportSlides({
       await fs.rm(writeToDisk, { force: true, recursive: true })
       await fs.mkdir(writeToDisk, { recursive: true })
     }
+    // Typo fix: perSlidei -> perSlide
     return perSlide
       ? genPagePngPerSlide(writeToDisk)
       : genPagePngOnePiece(writeToDisk)
@@ -574,6 +657,8 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
   const {
     entry,
     output,
+    handout,
+    cover,
     format,
     timeout,
     wait,
@@ -590,6 +675,8 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
   outFilename = output || options.data.config.exportFilename || outFilename || `${path.basename(entry, '.md')}-export`
   return {
     output: outFilename,
+    handout: handout || false,
+    cover: cover || false,
     slides: options.data.slides,
     total: options.data.slides.length,
     range,
diff --git a/packages/slidev/node/virtual/handout-components.ts b/packages/slidev/node/virtual/handout-components.ts
new file mode 100644
index 0000000000..3a24665945
--- /dev/null
+++ b/packages/slidev/node/virtual/handout-components.ts
@@ -0,0 +1,34 @@
+import type { VirtualModuleTemplate } from './types'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { toAtFS } from '../resolver'
+
+function createHandoutComponentTemplate(name: 'handout-bottom' | 'handout-cover'): VirtualModuleTemplate {
+  return {
+    id: `/@slidev/global-components/${name}`,
+    getContent({ roots }) {
+      const candidates = name === 'handout-bottom'
+        ? ['handout-bottom.vue', 'HandoutBottom.vue']
+        : ['handout-cover.vue', 'HandoutCover.vue']
+
+      const components = roots
+        .flatMap(root => candidates.map(n => join(root, n)))
+        .filter(p => existsSync(p))
+
+      if (components.length === 0) {
+        // Return an empty component
+        return `export default { render: () => null }`
+      }
+
+      const key = name.replace('-', '_')
+      const imports = components.map((p, i) => `import __h${key}_${i} from '${toAtFS(p)}'`).join('\n')
+      // Explicitly declare and forward pageNumber (kebab or camelCase) so
+      // overrides using defineProps<{ pageNumber: number }>() receive it.
+      const body = `export default {\n  name: 'SlidevGlobal_${key}',\n  inheritAttrs: false,\n  props: { pageNumber: Number },\n  setup(props, { attrs }) {\n    const camelize = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase())\n    function normalize(p) {\n      const out = {}\n      for (const k in p) out[camelize(k)] = p[k]\n      return out\n    }\n    return () => [${components.map((_, i) => `h(__h${key}_${i}, { ...normalize(attrs), pageNumber: props.pageNumber })`).join(',')}]\n  }\n}`
+      return [imports, `import { h } from 'vue'`, body].join('\n')
+    },
+  }
+}
+
+export const templateGlobalHandoutBottom = createHandoutComponentTemplate('handout-bottom')
+export const templateGlobalHandoutCover = createHandoutComponentTemplate('handout-cover')
diff --git a/packages/slidev/node/virtual/index.ts b/packages/slidev/node/virtual/index.ts
index 597d3e6077..fef46c8649 100644
--- a/packages/slidev/node/virtual/index.ts
+++ b/packages/slidev/node/virtual/index.ts
@@ -1,6 +1,7 @@
 import { templateConfigs } from './configs'
 import { templateLegacyRoutes, templateLegacyTitles } from './deprecated'
 import { templateGlobalLayers } from './global-layers'
+import { templateGlobalHandoutBottom, templateGlobalHandoutCover } from './handout-components'
 import { templateLayouts } from './layouts'
 import { templateMonacoRunDeps } from './monaco-deps'
 import { templateMonacoTypes } from './monaco-types'
@@ -18,6 +19,8 @@ export const templates = [
   templateConfigs,
   templateStyle,
   templateGlobalLayers,
+  templateGlobalHandoutBottom,
+  templateGlobalHandoutCover,
   templateNavControls,
   templateSlides,
   templateLayouts,
diff --git a/packages/types/client.d.ts b/packages/types/client.d.ts
index f1a0065af1..e1ad9e3f31 100644
--- a/packages/types/client.d.ts
+++ b/packages/types/client.d.ts
@@ -18,6 +18,20 @@ declare module '#slidev/global-layers' {
   export const SlideBottom: ComponentOptions
 }
 
+declare module '#slidev/global-components/handout-bottom' {
+  import type { ComponentOptions } from 'vue'
+
+  const component: ComponentOptions
+  export default component
+}
+
+declare module '#slidev/global-components/handout-cover' {
+  import type { ComponentOptions } from 'vue'
+
+  const component: ComponentOptions
+  export default component
+}
+
 declare module '#slidev/slides' {
   import type { SlideRoute } from '@slidev/types'
   import type { ShallowRef } from 'vue'
diff --git a/packages/types/src/cli.ts b/packages/types/src/cli.ts
index f2821d88ec..061e5d4ab9 100644
--- a/packages/types/src/cli.ts
+++ b/packages/types/src/cli.ts
@@ -5,6 +5,8 @@ export interface CommonArgs {
 
 export interface ExportArgs extends CommonArgs {
   'output'?: string
+  'handout'?: boolean
+  'cover'?: boolean
   'format'?: string
   'timeout'?: number
   'wait'?: number

From ded6031da83945ad109eb1ef261ecfe3cc5aa130 Mon Sep 17 00:00:00 2001
From: Oliver-Tobias Ripka <contact@oripka.de>
Date: Tue, 23 Sep 2025 09:56:35 +0200
Subject: [PATCH 2/3] feat: add ending page, support other formats than a4,
 cleanup, add docs

---
 demo/starter/handout-bottom.vue               |  19 ++-
 demo/starter/handout-cover.vue                | 111 ++++++++++++------
 demo/starter/handout-ending.vue               |  71 +++++++++++
 docs/builtin/cli.md                           |   9 ++
 docs/custom/index.md                          |  14 +++
 docs/guide/exporting.md                       |  32 +++++
 packages/client/composables/usePrintStyles.ts |  37 +++++-
 packages/client/internals/PrintHandout.vue    |  21 ++--
 packages/client/pages/cover/print.vue         |  11 +-
 packages/client/pages/handout/print.vue       | 103 ++++++++++++----
 packages/parser/src/config.ts                 | 102 +++++++++++++++-
 packages/slidev/node/cli.ts                   |  12 +-
 packages/slidev/node/commands/export.ts       |  30 ++++-
 .../slidev/node/virtual/handout-components.ts |   7 +-
 packages/slidev/node/virtual/index.ts         |   3 +-
 packages/types/client.d.ts                    |   7 ++
 packages/types/src/cli.ts                     |   1 +
 packages/types/src/config.ts                  |  20 ++++
 packages/types/src/frontmatter.ts             |  45 +++++++
 19 files changed, 565 insertions(+), 90 deletions(-)
 create mode 100644 demo/starter/handout-ending.vue

diff --git a/demo/starter/handout-bottom.vue b/demo/starter/handout-bottom.vue
index 74c358c632..5d6bc4ee79 100644
--- a/demo/starter/handout-bottom.vue
+++ b/demo/starter/handout-bottom.vue
@@ -6,7 +6,8 @@ defineProps<{ pageNumber: number }>()
 const year = new Date().getFullYear()
 // Replace these with your flavor system if needed
 const company = 'Slidev'
-const rightText = 'Presentation slides for developers'
+const rightText = 'Professional courses for developers'
+const series = 'Engineering Enablement Series'
 </script>
 
 <template>
@@ -15,8 +16,14 @@ const rightText = 'Presentation slides for developers'
       <div class="left">
         © {{ year }} {{ company }}
       </div>
+      <div class="center">
+        Page {{ pageNumber }}
+      </div>
       <div class="right">
-        {{ rightText }}
+        <span class="block font-semibold uppercase tracking-wide text-xs text-gray-500">
+          {{ series }}
+        </span>
+        <span>{{ rightText }}</span>
       </div>
     </div>
   </div>
@@ -35,7 +42,15 @@ const rightText = 'Presentation slides for developers'
   padding-top: 3mm; /* space below the rule drawn by container */
 }
 .left,
+.center,
 .right {
   white-space: nowrap;
 }
+.center {
+  font-variant-numeric: tabular-nums;
+  color: rgba(0, 0, 0, 0.7);
+}
+.right {
+  text-align: right;
+}
 </style>
diff --git a/demo/starter/handout-cover.vue b/demo/starter/handout-cover.vue
index 3c5728d3e8..b86b5095b4 100644
--- a/demo/starter/handout-cover.vue
+++ b/demo/starter/handout-cover.vue
@@ -1,50 +1,85 @@
 <template>
   <div>
-    <div class="break-after-page">
-      <span class="font-bold text-xl border-b-4 border-r-4 px-1 py-1 border-gray-800 ">
-        SLIDEV
-      </span>
-      <div class="h-56" />
-      <div class="max-w-md w-full mx-auto">
-        <div class="w-120 mx-auto font-bold flex flex-wrap gap-4">
-          <h1 class="text-5xl font-bold border-b-4 border-gray-800">
-            Welcome to Slidev
-          </h1>
-          v1.0
-        </div>
-        <div class="h-32" />
-        <div class="text-2xl font-bold mx-auto w-120 text-right">
+    <div
+      data-handout-page
+      class="break-after-page h-[270mm] px-16 py-20 flex flex-col justify-between text-slate-900 bg-gradient-to-br from-slate-50 via-white to-slate-100"
+    >
+      <div>
+        <span class="tracking-[0.35em] text-xs font-semibold uppercase text-sky-600">
           Slidev Starter Template
+        </span>
+        <h1 class="mt-6 text-6xl font-bold border-b-4 border-slate-900 inline-block pr-4">
+          Welcome to Slidev
+        </h1>
+        <p class="mt-6 max-w-xl text-lg leading-relaxed text-slate-700">
+          A companion handout for the demo deck that showcases Slidev's text-first authoring, navigation helpers, and Vue-driven
+          enhancements. Explore the pages ahead to follow along without missing any of the live interactions.
+        </p>
+        <div class="mt-10 flex flex-wrap gap-3 text-xs font-semibold uppercase tracking-[0.3em] text-slate-500">
+          <span class="bg-white/80 px-3 py-2 rounded-full border border-slate-200">Markdown Workflow</span>
+          <span class="bg-white/80 px-3 py-2 rounded-full border border-slate-200">Developer Features</span>
+          <span class="bg-white/80 px-3 py-2 rounded-full border border-slate-200">Interactive Demos</span>
         </div>
       </div>
-    </div>
-    <div class="break-after-page mt-68 mx-8 ">
-      <div class="font-bold text-xl mt-8">
-        COPYRIGHT
-      </div>
-      <div class="flex flex-row gap-4 mt-4 align-center items-center">
-        © {{ new Date().getFullYear().toString() }} Slidev.
+      <div class="flex justify-between text-sm font-semibold uppercase tracking-wide text-slate-500">
+        <span>{{ new Date().toLocaleDateString() }}</span>
+        <span>Prepared by the Slidev Team</span>
       </div>
+    </div>
+    <div
+      data-handout-page
+      class="break-after-page px-16 py-20 text-slate-800 leading-relaxed"
+    >
+      <h2 class="text-2xl font-bold tracking-tight text-slate-900">
+        Inside this deck
+      </h2>
       <p class="mt-4">
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
+        The slides introduce Slidev, how to navigate a live presentation, and the built-in developer tooling that powers code-focused
+        talks. Use this page as a quick reference for the sections you will encounter.
       </p>
-      <p class="mt-4">
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
+      <div class="grid grid-cols-2 gap-10 mt-10 text-sm">
+        <div>
+          <h3 class="text-xs font-semibold uppercase tracking-widest text-slate-500">
+            Highlights
+          </h3>
+          <ul class="mt-3 space-y-2">
+            <li>• Welcome tour of the starter theme</li>
+            <li>• Why Slidev embraces a text-based workflow</li>
+            <li>• Navigation tips and keyboard shortcuts</li>
+            <li>• Code demos with live annotations</li>
+          </ul>
+        </div>
+        <div>
+          <h3 class="text-xs font-semibold uppercase tracking-widest text-slate-500">
+            Keep an eye out for
+          </h3>
+          <ul class="mt-3 space-y-2">
+            <li>• Embedded <code>&lt;Toc&gt;</code> components for structure</li>
+            <li>• Magic Move transitions between code samples</li>
+            <li>• UnoCSS utilities applied per-slide</li>
+            <li>• Links to deeper documentation throughout</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+    <div
+      data-handout-page
+      class="px-16 py-20 text-slate-700 leading-relaxed"
+    >
+      <h2 class="text-2xl font-bold tracking-tight text-slate-900">
+        Adapting the starter
+      </h2>
+      <p class="mt-4 text-sm">
+        Reuse the patterns demonstrated in this deck when crafting your own Slidev presentations. The guidelines below mirror the
+        recommendations sprinkled across the slides.
       </p>
-      <p class="mt-4">
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFMERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
+      <ol class="mt-6 space-y-3 text-sm list-decimal list-inside">
+        <li>Begin with Markdown content, then enhance with Vue components only where interactivity adds clarity.</li>
+        <li>Leverage theme tokens and utilities for consistent typography across slides and handouts.</li>
+        <li>Document keyboard shortcuts and navigation cues so audiences can revisit the material asynchronously.</li>
+      </ol>
+      <p class="mt-6 text-xs uppercase tracking-widest text-slate-500">
+        Questions? Join the community on Discord or visit sli.dev for more examples.
       </p>
     </div>
   </div>
diff --git a/demo/starter/handout-ending.vue b/demo/starter/handout-ending.vue
new file mode 100644
index 0000000000..457f696e6b
--- /dev/null
+++ b/demo/starter/handout-ending.vue
@@ -0,0 +1,71 @@
+<template>
+  <div class="text-slate-800">
+    <div
+      data-handout-page
+      class="break-after-page px-16 py-20 leading-relaxed bg-white"
+    >
+      <h2 class="text-3xl font-bold tracking-tight text-slate-900">
+        Keep exploring Slidev
+      </h2>
+      <p class="mt-6 text-sm max-w-2xl">
+        This demo highlighted Slidev's text-centric authoring, navigation aids, and live coding capabilities. Use the prompts below
+        to turn the starter deck into your own developer-friendly presentations.
+      </p>
+      <div class="mt-12 grid grid-cols-2 gap-10 text-sm">
+        <div>
+          <h3 class="uppercase text-xs tracking-widest font-semibold text-slate-500">
+            Try it yourself
+          </h3>
+          <ol class="mt-3 space-y-2 list-decimal list-inside">
+            <li>Run <code>pnpm dev</code> and explore the navigation drawer and presenter mode.</li>
+            <li>Swap the welcome slide content and background image to match your story.</li>
+            <li>Embed a Vue component or external code sample to showcase interactive docs.</li>
+          </ol>
+        </div>
+        <div>
+          <h3 class="uppercase text-xs tracking-widest font-semibold text-slate-500">
+            Enhance your deck
+          </h3>
+          <ul class="mt-3 space-y-2">
+            <li>• Document useful keyboard shortcuts in early slides.</li>
+            <li>• Use the <code>&lt;Toc&gt;</code> component to keep longer talks scannable.</li>
+            <li>• Apply UnoCSS utilities or scoped styles to reinforce your brand.</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+    <div
+      data-handout-page
+      class="px-16 py-20 bg-white leading-relaxed"
+    >
+      <h2 class="text-2xl font-semibold tracking-tight text-slate-900">
+        Resources &amp; community
+      </h2>
+      <p class="mt-4 text-sm">
+        Continue learning with the official guides and community spaces below. They mirror the references called out across the
+        slides and help you dive deeper into advanced workflows.
+      </p>
+      <div class="mt-8 space-y-4 text-sm">
+        <div>
+          <h3 class="font-semibold text-slate-600">
+            Documentation quick hits
+          </h3>
+          <ul class="mt-2 space-y-1">
+            <li><strong>sli.dev/guide/why</strong> — Understand the philosophy behind text-first slides</li>
+            <li><strong>sli.dev/guide/ui</strong> — Learn every navigation control shown in the demo</li>
+            <li><strong>sli.dev/features/line-highlighting</strong> — Recreate the code walkthrough effects</li>
+          </ul>
+        </div>
+        <div>
+          <h3 class="font-semibold text-slate-600">
+            Stay in touch
+          </h3>
+          <p class="mt-2">
+            Join the community on <strong>Discord</strong>, follow <strong>@slidevjs</strong> for release news, or browse the
+            theme gallery for inspiration. Share what you build — we love seeing Slidev in the wild!
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/docs/builtin/cli.md b/docs/builtin/cli.md
index c9a748e4e2..c47b421588 100644
--- a/docs/builtin/cli.md
+++ b/docs/builtin/cli.md
@@ -69,13 +69,22 @@ Export slides to PDF (or other format). See <LinkInline link="guide/exporting" /
 Options:
 
 - `--output` (`string`, default: use `exportFilename` (see https://sli.dev/custom/#frontmatter-configures) or use `[entry]-export`): path to the output.
+- `--handout` (`boolean`, default: `false`): generate a companion handout PDF (notes + footer) using the configured paper size.
+- `--cover` (`boolean`, default: `false`): prepend global cover pages from `handout-cover.vue` when handouts are exported.
+- `--ending` (`boolean`, default: `false`): append closing pages from `handout-ending.vue` when handouts are exported.
 - `--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).
+- `--wait` (`number`, default: `0`): wait the specified milliseconds before capturing each slide.
+- `--wait-until` (`'networkidle', 'load', 'domcontentloaded', 'none'`, default: `'networkidle'`): wait for a specific Playwright event before each capture.
 - `--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.
+- `--executable-path` (`string`): provide a custom Chromium/Chrome executable for Playwright.
 - `--omit-background` (`boolean`, default: `false`): remove the default browser background
+- `--with-toc` (`boolean`, default: `false`): generate a PDF outline when exporting to PDF.
+- `--per-slide` (`boolean`, default: `false`): render each slide in isolation. Useful for heavy global components.
+- `--scale` (`number`, default: `2`): device scale factor for non-handout exports.
 
 ## `slidev format [entry]` {#format}
 
diff --git a/docs/custom/index.md b/docs/custom/index.md
index 2022e93152..3680e1a33d 100644
--- a/docs/custom/index.md
+++ b/docs/custom/index.md
@@ -42,6 +42,20 @@ export:
   dark: false
   withClicks: false
   withToc: false
+# handout export presets (paper size, margins, cover margins)
+handout:
+  size: A4
+  orientation: portrait
+  margins:
+    top: 0cm
+    bottom: 0cm
+    left: 0cm
+    right: 0cm
+  coverMargins:
+    top: 1cm
+    bottom: 1cm
+    left: 1.5cm
+    right: 1.5cm
 # enable twoslash, can be boolean, 'dev' or 'build'
 twoslash: true
 # show line numbers in code blocks
diff --git a/docs/guide/exporting.md b/docs/guide/exporting.md
index 6e27dcfcda..30ebe338d8 100644
--- a/docs/guide/exporting.md
+++ b/docs/guide/exporting.md
@@ -189,6 +189,38 @@ Chromium may miss some features like codecs that are required to decode some vid
 $ slidev export --executable-path [path_to_chromium]
 ```
 
+### Handout exports
+
+Use the `--handout` flag to render an A4 (or customised) PDF that places each slide above its speaker notes and a shared footer component. Slidev writes this PDF alongside your primary export using the suffix `-handout.pdf`:
+
+```bash
+$ slidev export --handout
+```
+
+You can prepend multi-page covers with `--cover` and append closing/appendix pages with `--ending`. Both switches look for global Vue components in the project root (`handout-cover.vue` and `handout-ending.vue`). Any element with the UnoCSS utility `break-after-page` (or a `data-handout-page` attribute) forces an additional printed page, making it easy to create multi-page introductions or wrap-up sections.
+
+Paper size and margins are configurable from the deck headmatter:
+
+```yaml
+---
+handout:
+  size: letter # or A4, Legal, Tabloid …
+  orientation: landscape
+  margins:
+    top: 0.5in
+    bottom: 0.5in
+    left: 0.75in
+    right: 0.75in
+  coverMargins:
+    top: 1cm
+    bottom: 1cm
+    left: 1.5cm
+    right: 1.5cm
+---
+```
+
+The `size` option accepts common international formats (A3, A4, A5) and North American sizes (Letter, Legal, Tabloid, Executive). Provide both `width` and `height` to specify a custom paper size.
+
 ### PDF Outline
 
 > Available since v0.36.10
diff --git a/packages/client/composables/usePrintStyles.ts b/packages/client/composables/usePrintStyles.ts
index a8693c8ee8..02fdb2812e 100644
--- a/packages/client/composables/usePrintStyles.ts
+++ b/packages/client/composables/usePrintStyles.ts
@@ -1,7 +1,7 @@
 import { useStyleTag } from '@vueuse/core'
 import { computed } from 'vue'
 import { useRoute } from 'vue-router'
-import { slideHeight, slideWidth } from '../env'
+import { configs, slideHeight, slideWidth } from '../env'
 import { useNav } from './useNav'
 
 export function usePrintStyles() {
@@ -30,3 +30,38 @@ export function patchMonacoColors() {
     el.media = ''
   })
 }
+
+export type HandoutPageContext = 'handout' | 'cover' | 'ending'
+
+export function useHandoutPageSetup(context: HandoutPageContext = 'handout') {
+  const { isPrintMode } = useNav()
+  const route = useRoute()
+
+  const allowedRoute = computed(() => {
+    if (context === 'cover')
+      return route.name === 'cover'
+    return route.name === 'handout'
+  })
+
+  const margins = computed(() => context === 'cover'
+    ? configs.handout.coverMargins
+    : configs.handout.margins)
+  const pageSize = computed(() => configs.handout.cssPageSize)
+
+  useStyleTag(computed(() => (isPrintMode.value && allowedRoute.value)
+    ? `
+@page {
+  size: ${pageSize.value};
+  margin-top: ${margins.value.top};
+  margin-right: ${margins.value.right};
+  margin-bottom: ${margins.value.bottom};
+  margin-left: ${margins.value.left};
+}
+`
+    : ''))
+
+  return {
+    margins,
+    pageSize,
+  }
+}
diff --git a/packages/client/internals/PrintHandout.vue b/packages/client/internals/PrintHandout.vue
index c10932e866..aa62db357d 100644
--- a/packages/client/internals/PrintHandout.vue
+++ b/packages/client/internals/PrintHandout.vue
@@ -2,7 +2,7 @@
 import type { SlideRoute } from '@slidev/types'
 import HandoutBottom from '#slidev/global-components/handout-bottom'
 import { computed } from 'vue'
-import { slideHeight, slideWidth } from '../env'
+import { configs, slideHeight, slideWidth } from '../env'
 import NoteDisplay from './NoteDisplay.vue'
 import PrintSlide from './PrintSlide.vue'
 
@@ -14,12 +14,11 @@ const props = defineProps<{
 const route = computed(() => props.route)
 const pageOffset = computed(() => props.pageOffset ?? 0)
 
-// Use fixed A4 dimensions in CSS pixels (96 DPI) to avoid relying on
+// Use configured dimensions (converted to CSS pixels at 96 DPI) to avoid relying on
 // runtime viewport sizes which can skew scaling during headless export
-const PAGE_WIDTH_PX = Math.round(210 / 25.4 * 96)
-const PAGE_HEIGHT_PX = Math.round(297 / 25.4 * 96)
-const pageWidth = computed(() => PAGE_WIDTH_PX)
-const pageHeight = computed(() => PAGE_HEIGHT_PX)
+const handoutOptions = computed(() => configs.handout)
+const pageWidth = computed(() => handoutOptions.value.widthPx)
+const pageHeight = computed(() => handoutOptions.value.heightPx)
 
 // Target layout: slide ~50% height, notes the rest, footer pinned
 const SLIDE_PORTION = 0.5
@@ -47,10 +46,14 @@ const slideAreaStyle = computed(() => ({
   height: `${slideHeightScaled.value}px`,
   padding: `${SLIDE_TOP_MARGIN_MM}mm ${SLIDE_SIDE_MARGIN_MM}mm 0`,
 }))
+const pageBoxStyle = computed(() => ({
+  width: `${handoutOptions.value.widthMm}mm`,
+  minHeight: `${handoutOptions.value.heightMm}mm`,
+}))
 </script>
 
 <template>
-  <div class="break-after-page page">
+  <div class="break-after-page page" :style="pageBoxStyle">
     <div class="slide-area" :style="slideAreaStyle">
       <div class="slide-scale-wrap" :style="{ width: `${slideWidth}px`, height: `${slideHeight}px`, transform: `scale(${scale})` }">
         <PrintSlide :route="route" />
@@ -72,12 +75,10 @@ const slideAreaStyle = computed(() => ({
 </template>
 
 <style scoped>
-/* One handout page per printed page, sized to A4 with internal padding */
+/* One handout page per printed page, sized via inline styles with internal padding */
 .page {
   display: flex;
   flex-direction: column;
-  width: 210mm;
-  min-height: 297mm;
   margin: 0 auto;
   padding: 10mm 12mm 4mm; /* top, sides, bottom */
 
diff --git a/packages/client/pages/cover/print.vue b/packages/client/pages/cover/print.vue
index f41a17d22a..218c19ab0c 100644
--- a/packages/client/pages/cover/print.vue
+++ b/packages/client/pages/cover/print.vue
@@ -2,10 +2,13 @@
 import HandoutCover from '#slidev/global-components/handout-cover'
 import { watchEffect } from 'vue'
 import { useNav } from '../../composables/useNav'
+import { useHandoutPageSetup } from '../../composables/usePrintStyles'
 import { themeVars } from '../../env'
 
 const { isPrintMode } = useNav()
 
+useHandoutPageSetup('cover')
+
 watchEffect(() => {
   const html = document.body.parentNode as HTMLElement
   if (isPrintMode.value)
@@ -51,12 +54,4 @@ html.print body {
   float: none;
   overflow: visible;
 }
-
-@page {
-  size: A4;
-  margin-top: 1cm;
-  margin-bottom: 1cm;
-  margin-left: 1.5cm;
-  margin-right: 1.5cm;
-}
 </style>
diff --git a/packages/client/pages/handout/print.vue b/packages/client/pages/handout/print.vue
index e800f9ceb8..a1067e7956 100644
--- a/packages/client/pages/handout/print.vue
+++ b/packages/client/pages/handout/print.vue
@@ -1,21 +1,34 @@
 <script setup lang="ts">
+import type { Ref } from 'vue'
 import HandoutCover from '#slidev/global-components/handout-cover'
+import HandoutEnding from '#slidev/global-components/handout-ending'
 import { useElementSize } from '@vueuse/core'
-import { computed, nextTick, onMounted, ref, watchEffect } from 'vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch, watchEffect } from 'vue'
 import { useRoute } from 'vue-router'
 import { useNav } from '../../composables/useNav'
+import { useHandoutPageSetup } from '../../composables/usePrintStyles'
 import { themeVars } from '../../env'
 import PrintContainerHandout from '../../internals/PrintContainerHandout.vue'
 import { windowSize } from '../../state'
 
-const { isPrintMode } = useNav()
+const { isPrintMode, printRange } = useNav()
+
+useHandoutPageSetup('handout')
 
 const root = ref<HTMLElement | null>(null)
 const { width: rootWidth } = useElementSize(root)
 const route = useRoute()
 const includeCover = computed(() => route.query.cover != null)
+const includeEnding = computed(() => route.query.ending != null)
 const coverRoot = ref<HTMLElement | null>(null)
+const endingRoot = ref<HTMLElement | null>(null)
 const pageOffset = ref(0)
+const endingPageCount = ref(0)
+
+const slidePageCount = computed(() => printRange.value.length)
+const endingPageDisplayCount = computed(() => includeEnding.value ? endingPageCount.value : 0)
+const endingPageStart = computed(() => pageOffset.value + slidePageCount.value + 1)
+const totalPageCount = computed(() => pageOffset.value + slidePageCount.value + endingPageDisplayCount.value)
 
 watchEffect(() => {
   const html = document.body.parentNode as HTMLElement
@@ -25,32 +38,81 @@ watchEffect(() => {
     html.classList.remove('print')
 })
 
+function detectPageBlocks(el: HTMLElement | null, fallback: number) {
+  if (!el)
+    return fallback
+  const hasContent = el.childElementCount > 0
+  const selectors = ['.break-after-page', '[data-handout-page]']
+  const candidates = new Set<HTMLElement>(Array.from(el.querySelectorAll<HTMLElement>(selectors.join(','))))
+  const inlineBreaks = Array.from(el.querySelectorAll<HTMLElement>('[style]')).filter((node) => {
+    const style = node.getAttribute('style') || ''
+    return /page-break-after\s*:\s*always/i.test(style) || /break-after\s*:\s*page/i.test(style)
+  })
+  inlineBreaks.forEach(node => candidates.add(node))
+  if (candidates.size > 0)
+    return candidates.size
+  const directChildren = Array.from(el.children).filter((node): node is HTMLElement => node instanceof HTMLElement)
+  const directCount = directChildren.filter(node => node.classList.contains('break-after-page') || node.hasAttribute('data-handout-page')).length
+  if (directCount > 0)
+    return directCount
+  return hasContent ? Math.max(1, fallback) : fallback
+}
+
 function recountCoverPages() {
   if (!includeCover.value) {
     pageOffset.value = 0
     return
   }
-  const el = coverRoot.value
-  if (!el) {
-    pageOffset.value = 1
+  pageOffset.value = Math.max(1, detectPageBlocks(coverRoot.value, 1))
+}
+
+function recountEndingPages() {
+  if (!includeEnding.value) {
+    endingPageCount.value = 0
     return
   }
-  // Heuristic: count elements intended to force page breaks.
-  // UnoCSS utility `break-after-page` is commonly used.
-  // If none found, assume a single-page cover.
-  const blocks = el.querySelectorAll('.break-after-page')
-  pageOffset.value = Math.max(1, blocks.length)
+  endingPageCount.value = detectPageBlocks(endingRoot.value, 0)
 }
 
+function setupMutationObserver(target: Ref<HTMLElement | null>, callback: () => void) {
+  if (typeof MutationObserver === 'undefined')
+    return
+  let observer: MutationObserver | null = null
+  watch(target, (el) => {
+    observer?.disconnect()
+    if (el) {
+      observer = new MutationObserver(() => callback())
+      observer.observe(el, { childList: true, subtree: true, attributes: true })
+    }
+  }, { immediate: true })
+  onBeforeUnmount(() => observer?.disconnect())
+}
+
+setupMutationObserver(coverRoot, () => recountCoverPages())
+setupMutationObserver(endingRoot, () => recountEndingPages())
+
 onMounted(async () => {
   await nextTick()
   recountCoverPages()
+  recountEndingPages()
 })
 
 watchEffect(() => {
   // Recount when toggling cover or when printing state changes
-  if (isPrintMode.value)
+  if (isPrintMode.value) {
     recountCoverPages()
+    recountEndingPages()
+  }
+})
+
+watch(includeCover, async () => {
+  await nextTick()
+  recountCoverPages()
+})
+
+watch(includeEnding, async () => {
+  await nextTick()
+  recountEndingPages()
 })
 </script>
 
@@ -65,6 +127,15 @@ watchEffect(() => {
       :width="rootWidth || windowSize.width.value"
       :page-offset="pageOffset"
     />
+    <div v-if="includeEnding" ref="endingRoot">
+      <HandoutEnding
+        :page-start="endingPageStart"
+        :page-count="endingPageDisplayCount"
+        :total-pages="totalPageCount"
+        :cover-count="pageOffset"
+        :slide-count="slidePageCount"
+      />
+    </div>
   </div>
 </template>
 
@@ -102,13 +173,5 @@ html.print body {
   overflow: visible;
 }
 
-/* Cover content may contain its own break-after-page blocks to form pages */
-
-@page {
-  size: A4;
-  margin-top: 0cm;
-  margin-bottom: 0cm;
-  margin-left: 0cm;
-  margin-right: 0cm;
-}
+/* Cover/ending content may contain their own break-after-page blocks to form pages */
 </style>
diff --git a/packages/parser/src/config.ts b/packages/parser/src/config.ts
index 52fbb03da8..4883fc283f 100644
--- a/packages/parser/src/config.ts
+++ b/packages/parser/src/config.ts
@@ -1,4 +1,4 @@
-import type { DrawingsOptions, FontOptions, ResolvedDrawingsOptions, ResolvedExportOptions, ResolvedFontOptions, SlidevConfig, SlidevThemeMeta } from '@slidev/types'
+import type { DrawingsOptions, FontOptions, HandoutOptions, ResolvedDrawingsOptions, ResolvedExportOptions, ResolvedFontOptions, ResolvedHandoutOptions, SlidevConfig, SlidevThemeMeta } from '@slidev/types'
 import { toArray, uniq } from '@antfu/utils'
 import { parseAspectRatio } from './utils'
 
@@ -45,6 +45,7 @@ export function getDefaultConfig(): SlidevConfig {
     remote: false,
     mdc: false,
     seoMeta: {},
+    handout: resolveHandoutOptions(),
   }
 }
 
@@ -78,6 +79,8 @@ export function resolveConfig(headmatter: any, themeMeta: SlidevThemeMeta = {},
     },
   }
 
+  config.handout = resolveHandoutOptions(config.handout)
+
   // @ts-expect-error compat
   if (config.highlighter === 'shikiji') {
     console.warn(`[slidev] "shikiji" is merged back to "shiki", you can safely change it "highlighter: shiki"`)
@@ -204,6 +207,103 @@ export function resolveFonts(fonts: FontOptions = {}): ResolvedFontOptions {
   }
 }
 
+const PAPER_SIZES_MM: Record<string, { label: string, mm: [number, number] }> = {
+  a5: { label: 'A5', mm: [148, 210] },
+  a4: { label: 'A4', mm: [210, 297] },
+  a3: { label: 'A3', mm: [297, 420] },
+  letter: { label: 'letter', mm: [215.9, 279.4] },
+  legal: { label: 'legal', mm: [215.9, 355.6] },
+  tabloid: { label: 'tabloid', mm: [279.4, 431.8] },
+  executive: { label: 'executive', mm: [184.15, 266.7] },
+}
+
+const PX_PER_MM = 96 / 25.4
+const DEFAULT_HANDOUT_MARGINS = { top: '0cm', right: '0cm', bottom: '0cm', left: '0cm' } as const
+const DEFAULT_HANDOUT_COVER_MARGINS = { top: '1cm', right: '1.5cm', bottom: '1cm', left: '1.5cm' } as const
+
+function formatMm(value: number): string {
+  return `${Number(value.toFixed(3))}mm`
+}
+
+function normalizeMargins(
+  input: string | Partial<Record<'top' | 'right' | 'bottom' | 'left', string>> | undefined,
+  fallback: ResolvedHandoutOptions['margins'],
+): ResolvedHandoutOptions['margins'] {
+  if (!input)
+    return { ...fallback }
+  if (typeof input === 'string') {
+    return {
+      top: input,
+      right: input,
+      bottom: input,
+      left: input,
+    }
+  }
+  return {
+    top: input.top ?? fallback.top,
+    right: input.right ?? fallback.right,
+    bottom: input.bottom ?? fallback.bottom,
+    left: input.left ?? fallback.left,
+  }
+}
+
+export function resolveHandoutOptions(
+  options: HandoutOptions | ResolvedHandoutOptions | undefined = undefined,
+): ResolvedHandoutOptions {
+  if (options && typeof options === 'object' && 'widthMm' in options && 'heightMm' in options && 'cssPageSize' in options) {
+    return {
+      ...options,
+      margins: { ...options.margins },
+      coverMargins: { ...options.coverMargins },
+    }
+  }
+
+  const normalized = typeof options === 'string' ? { size: options } : options || {}
+  const requestedKey = normalized.size ? normalized.size.toLowerCase() : 'a4'
+  const preset = PAPER_SIZES_MM[requestedKey] || PAPER_SIZES_MM.a4
+
+  let widthMm = normalized.width && normalized.height
+    ? normalized.unit === 'in'
+      ? normalized.width * 25.4
+      : normalized.width
+    : preset.mm[0]
+  let heightMm = normalized.width && normalized.height
+    ? normalized.unit === 'in'
+      ? normalized.height * 25.4
+      : normalized.height
+    : preset.mm[1]
+
+  const orientation = normalized.orientation
+    ?? (widthMm >= heightMm ? 'landscape' : 'portrait')
+
+  if (orientation === 'landscape' && heightMm > widthMm)
+    [widthMm, heightMm] = [heightMm, widthMm]
+  else if (orientation === 'portrait' && widthMm > heightMm)
+    [widthMm, heightMm] = [heightMm, widthMm]
+
+  const widthPx = Math.round(widthMm * PX_PER_MM)
+  const heightPx = Math.round(heightMm * PX_PER_MM)
+
+  const cssKeyword = preset.label
+  const cssPageSize = normalized.width && normalized.height
+    ? `${formatMm(widthMm)} ${formatMm(heightMm)}`
+    : orientation === 'landscape'
+      ? `${cssKeyword} landscape`
+      : cssKeyword
+
+  return {
+    size: normalized.width && normalized.height ? 'custom' : cssKeyword,
+    orientation,
+    widthMm,
+    heightMm,
+    widthPx,
+    heightPx,
+    cssPageSize,
+    margins: normalizeMargins(normalized.margins, DEFAULT_HANDOUT_MARGINS),
+    coverMargins: normalizeMargins(normalized.coverMargins, DEFAULT_HANDOUT_COVER_MARGINS),
+  }
+}
+
 function resolveDrawings(options: DrawingsOptions = {}, filepath?: string): ResolvedDrawingsOptions {
   const {
     enabled = true,
diff --git a/packages/slidev/node/cli.ts b/packages/slidev/node/cli.ts
index 4c6bbc34fe..b5799e7f8f 100644
--- a/packages/slidev/node/cli.ts
+++ b/packages/slidev/node/cli.ts
@@ -41,6 +41,10 @@ const FILES_CREATE_RESTART = [
   'global-top.vue',
   'handout-bottom.vue',
   'handout-cover.vue',
+  'handout-ending.vue',
+  'HandoutBottom.vue',
+  'HandoutCover.vue',
+  'HandoutEnding.vue',
   'uno.config.js',
   'uno.config.ts',
   'unocss.config.js',
@@ -588,11 +592,15 @@ function exportOptions<T>(args: Argv<T>) {
     })
     .option('handout', {
       type: 'boolean',
-      describe: 'export handout PDF (A4, one page per slide with notes and header/footer) to a separate file',
+      describe: 'export handout PDF (configurable page size, one page per slide with notes and header/footer) to a separate file',
     })
     .option('cover', {
       type: 'boolean',
-      describe: 'prepend a handout cover page if available (requires handout-cover.vue)',
+      describe: 'prepend handout cover page(s) if available (requires handout-cover.vue)',
+    })
+    .option('ending', {
+      type: 'boolean',
+      describe: 'append handout ending page(s) if available (requires handout-ending.vue)',
     })
     .option('format', {
       type: 'string',
diff --git a/packages/slidev/node/commands/export.ts b/packages/slidev/node/commands/export.ts
index e6a97693af..c6daa264e1 100644
--- a/packages/slidev/node/commands/export.ts
+++ b/packages/slidev/node/commands/export.ts
@@ -1,4 +1,4 @@
-import type { ExportArgs, ResolvedSlidevOptions, SlideInfo, TocItem } from '@slidev/types'
+import type { ExportArgs, ResolvedHandoutOptions, ResolvedSlidevOptions, SlideInfo, TocItem } from '@slidev/types'
 import { Buffer } from 'node:buffer'
 import fs from 'node:fs/promises'
 import path, { dirname, relative } from 'node:path'
@@ -23,6 +23,7 @@ export interface ExportOptions {
   output?: string
   handout?: boolean
   cover?: boolean
+  ending?: boolean
   timeout?: number
   wait?: number
   waitUntil: 'networkidle' | 'load' | 'domcontentloaded' | undefined
@@ -40,6 +41,7 @@ export interface ExportOptions {
   perSlide?: boolean
   scale?: number
   omitBackground?: boolean
+  handoutOptions?: ResolvedHandoutOptions
 }
 
 interface ExportPngResult {
@@ -173,6 +175,7 @@ export async function exportSlides({
   output = 'slides',
   handout = false,
   cover = false,
+  ending = false,
   slides,
   base = '/',
   timeout = 30000,
@@ -188,6 +191,7 @@ export async function exportSlides({
   scale = 1,
   waitUntil,
   omitBackground = false,
+  handoutOptions,
 }: ExportOptions) {
   const pages: number[] = parseRangeString(total, range)
 
@@ -198,11 +202,21 @@ export async function exportSlides({
   // Use a sane, stable viewport for handout printing to avoid extremely tall pages
   // that can cause Chromium to render black/blank pages when printing.
   // For regular slide export, keep the original large viewport behavior.
-  const A4_WIDTH_PX = Math.round(210 / 25.4 * 96)
-  const A4_HEIGHT_PX = Math.round(297 / 25.4 * 96)
+  const fallbackHandout: ResolvedHandoutOptions = {
+    size: 'A4',
+    orientation: 'portrait',
+    widthMm: 210,
+    heightMm: 297,
+    widthPx: Math.round(210 / 25.4 * 96),
+    heightPx: Math.round(297 / 25.4 * 96),
+    cssPageSize: 'A4',
+    margins: { top: '0cm', right: '0cm', bottom: '0cm', left: '0cm' },
+    coverMargins: { top: '1cm', right: '1.5cm', bottom: '1cm', left: '1.5cm' },
+  }
+  const handoutConfig = handoutOptions || fallbackHandout
   const context = await browser.newContext({
     viewport: handout
-      ? { width: A4_WIDTH_PX, height: A4_HEIGHT_PX }
+      ? { width: handoutConfig.widthPx, height: handoutConfig.heightPx }
       : {
           width,
           // Calculate height for every slides to be in the viewport to trigger the rendering of iframes (twitter, youtube...)
@@ -228,6 +242,8 @@ export async function exportSlides({
       qs.set('range', range)
     if (cover)
       qs.set('cover', 'true')
+    if (ending)
+      qs.set('ending', 'true')
     const handoutQuery = `?${qs.toString()}`
     const handoutPath = routerMode === 'hash'
       ? `http://localhost:${port}${base}${handoutQuery}#/handout`
@@ -272,7 +288,8 @@ export async function exportSlides({
     if (wait)
       await page.waitForTimeout(wait)
     await page.pdf({
-      format: 'A4',
+      width: `${handoutConfig.widthMm}mm`,
+      height: `${handoutConfig.heightMm}mm`,
       path: handoutOut,
       margin: { left: 0, top: 0, right: 0, bottom: 0 },
       printBackground: true,
@@ -659,6 +676,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
     output,
     handout,
     cover,
+    ending,
     format,
     timeout,
     wait,
@@ -677,6 +695,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
     output: outFilename,
     handout: handout || false,
     cover: cover || false,
+    ending: ending || false,
     slides: options.data.slides,
     total: options.data.slides.length,
     range,
@@ -694,6 +713,7 @@ export function getExportOptions(args: ExportArgs, options: ResolvedSlidevOption
     perSlide: perSlide || false,
     scale: scale || 2,
     omitBackground: omitBackground ?? false,
+    handoutOptions: options.data.config.handout,
   }
 }
 
diff --git a/packages/slidev/node/virtual/handout-components.ts b/packages/slidev/node/virtual/handout-components.ts
index 3a24665945..c7a4d5451d 100644
--- a/packages/slidev/node/virtual/handout-components.ts
+++ b/packages/slidev/node/virtual/handout-components.ts
@@ -3,13 +3,15 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { toAtFS } from '../resolver'
 
-function createHandoutComponentTemplate(name: 'handout-bottom' | 'handout-cover'): VirtualModuleTemplate {
+function createHandoutComponentTemplate(name: 'handout-bottom' | 'handout-cover' | 'handout-ending'): VirtualModuleTemplate {
   return {
     id: `/@slidev/global-components/${name}`,
     getContent({ roots }) {
       const candidates = name === 'handout-bottom'
         ? ['handout-bottom.vue', 'HandoutBottom.vue']
-        : ['handout-cover.vue', 'HandoutCover.vue']
+        : name === 'handout-cover'
+          ? ['handout-cover.vue', 'HandoutCover.vue']
+          : ['handout-ending.vue', 'HandoutEnding.vue']
 
       const components = roots
         .flatMap(root => candidates.map(n => join(root, n)))
@@ -32,3 +34,4 @@ function createHandoutComponentTemplate(name: 'handout-bottom' | 'handout-cover'
 
 export const templateGlobalHandoutBottom = createHandoutComponentTemplate('handout-bottom')
 export const templateGlobalHandoutCover = createHandoutComponentTemplate('handout-cover')
+export const templateGlobalHandoutEnding = createHandoutComponentTemplate('handout-ending')
diff --git a/packages/slidev/node/virtual/index.ts b/packages/slidev/node/virtual/index.ts
index fef46c8649..1f5c81a5c6 100644
--- a/packages/slidev/node/virtual/index.ts
+++ b/packages/slidev/node/virtual/index.ts
@@ -1,7 +1,7 @@
 import { templateConfigs } from './configs'
 import { templateLegacyRoutes, templateLegacyTitles } from './deprecated'
 import { templateGlobalLayers } from './global-layers'
-import { templateGlobalHandoutBottom, templateGlobalHandoutCover } from './handout-components'
+import { templateGlobalHandoutBottom, templateGlobalHandoutCover, templateGlobalHandoutEnding } from './handout-components'
 import { templateLayouts } from './layouts'
 import { templateMonacoRunDeps } from './monaco-deps'
 import { templateMonacoTypes } from './monaco-types'
@@ -21,6 +21,7 @@ export const templates = [
   templateGlobalLayers,
   templateGlobalHandoutBottom,
   templateGlobalHandoutCover,
+  templateGlobalHandoutEnding,
   templateNavControls,
   templateSlides,
   templateLayouts,
diff --git a/packages/types/client.d.ts b/packages/types/client.d.ts
index e1ad9e3f31..db7f319179 100644
--- a/packages/types/client.d.ts
+++ b/packages/types/client.d.ts
@@ -32,6 +32,13 @@ declare module '#slidev/global-components/handout-cover' {
   export default component
 }
 
+declare module '#slidev/global-components/handout-ending' {
+  import type { ComponentOptions } from 'vue'
+
+  const component: ComponentOptions
+  export default component
+}
+
 declare module '#slidev/slides' {
   import type { SlideRoute } from '@slidev/types'
   import type { ShallowRef } from 'vue'
diff --git a/packages/types/src/cli.ts b/packages/types/src/cli.ts
index 061e5d4ab9..ae629d75c6 100644
--- a/packages/types/src/cli.ts
+++ b/packages/types/src/cli.ts
@@ -7,6 +7,7 @@ export interface ExportArgs extends CommonArgs {
   'output'?: string
   'handout'?: boolean
   'cover'?: boolean
+  'ending'?: boolean
   'format'?: string
   'timeout'?: number
   'wait'?: number
diff --git a/packages/types/src/config.ts b/packages/types/src/config.ts
index fbe4dbdc11..96c477026b 100644
--- a/packages/types/src/config.ts
+++ b/packages/types/src/config.ts
@@ -6,6 +6,7 @@ export interface ResolvedSlidevConfigSub {
   drawings: ResolvedDrawingsOptions
   fonts: ResolvedFontOptions
   aspectRatio: number
+  handout: ResolvedHandoutOptions
 }
 
 export interface SlidevConfig extends
@@ -36,3 +37,22 @@ export interface ResolvedExportOptions extends Omit<ExportArgs, 'entry' | 'theme
   executablePath?: string
   withToc?: boolean
 }
+
+export interface ResolvedHandoutOptions {
+  size: string
+  orientation: 'portrait' | 'landscape'
+  widthMm: number
+  heightMm: number
+  widthPx: number
+  heightPx: number
+  cssPageSize: string
+  margins: HandoutPageMargins
+  coverMargins: HandoutPageMargins
+}
+
+export interface HandoutPageMargins {
+  top: string
+  right: string
+  bottom: string
+  left: string
+}
diff --git a/packages/types/src/frontmatter.ts b/packages/types/src/frontmatter.ts
index 4592cb9381..23dcd0e801 100644
--- a/packages/types/src/frontmatter.ts
+++ b/packages/types/src/frontmatter.ts
@@ -221,6 +221,12 @@ export interface HeadmatterConfig extends TransitionOptions {
    * @default ''
    */
   exportFilename?: string | null
+  /**
+   * Options for exported handouts (page size, orientation, margins).
+   *
+   * @default {}
+   */
+  handout?: HandoutOptions
   /**
    * Enable Monaco
    *
@@ -419,6 +425,45 @@ export interface FontOptions {
   fallbacks?: boolean
 }
 
+export type HandoutPredefinedSize = 'A5' | 'A4' | 'A3' | 'Letter' | 'Legal' | 'Tabloid' | 'Executive' | Lowercase<'A5' | 'A4' | 'A3' | 'Letter' | 'Legal' | 'Tabloid' | 'Executive'>
+
+export type HandoutPageMarginInput = Record<'top' | 'right' | 'bottom' | 'left', string>
+
+export interface HandoutOptions {
+  /**
+   * Predefined page size to use. Set `width`/`height` for custom sizes.
+   */
+  size?: HandoutPredefinedSize
+  /**
+   * Page orientation.
+   *
+   * @default 'portrait'
+   */
+  orientation?: 'portrait' | 'landscape'
+  /**
+   * Custom page width.
+   */
+  width?: number
+  /**
+   * Custom page height.
+   */
+  height?: number
+  /**
+   * Units for `width`/`height` when provided.
+   *
+   * @default 'mm'
+   */
+  unit?: 'mm' | 'in'
+  /**
+   * Margins applied to the handout pages. Can be a CSS shorthand string or per-side object.
+   */
+  margins?: string | Partial<HandoutPageMarginInput>
+  /**
+   * Margins applied specifically to the optional cover pages.
+   */
+  coverMargins?: string | Partial<HandoutPageMarginInput>
+}
+
 export type BuiltinSlideTransition = 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'fade' | 'zoom' | 'none'
 
 export interface TransitionOptions {

From 568e47a951f68f7c79664d284f59b06729e9dddd Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Tue, 23 Sep 2025 07:57:58 +0000
Subject: [PATCH 3/3] [autofix.ci] apply automated fixes

---
 packages/vscode/schema/headmatter.json | 117 +++++++++++++++++++++++++
 1 file changed, 117 insertions(+)

diff --git a/packages/vscode/schema/headmatter.json b/packages/vscode/schema/headmatter.json
index bed19a9401..97195d4d15 100644
--- a/packages/vscode/schema/headmatter.json
+++ b/packages/vscode/schema/headmatter.json
@@ -431,6 +431,12 @@
           "markdownDescription": "Force the filename used when exporting the presentation.\nThe extension, e.g. .pdf, gets automatically added.",
           "default": ""
         },
+        "handout": {
+          "$ref": "#/definitions/HandoutOptions",
+          "description": "Options for exported handouts (page size, orientation, margins).",
+          "markdownDescription": "Options for exported handouts (page size, orientation, margins).",
+          "default": {}
+        },
         "monaco": {
           "anyOf": [
             {
@@ -786,6 +792,117 @@
         }
       }
     },
+    "HandoutOptions": {
+      "type": "object",
+      "properties": {
+        "size": {
+          "$ref": "#/definitions/HandoutPredefinedSize",
+          "description": "Predefined page size to use. Set `width`/`height` for custom sizes.",
+          "markdownDescription": "Predefined page size to use. Set `width`/`height` for custom sizes."
+        },
+        "orientation": {
+          "type": "string",
+          "enum": [
+            "portrait",
+            "landscape"
+          ],
+          "description": "Page orientation.",
+          "markdownDescription": "Page orientation.",
+          "default": "portrait"
+        },
+        "width": {
+          "type": "number",
+          "description": "Custom page width.",
+          "markdownDescription": "Custom page width."
+        },
+        "height": {
+          "type": "number",
+          "description": "Custom page height.",
+          "markdownDescription": "Custom page height."
+        },
+        "unit": {
+          "type": "string",
+          "enum": [
+            "mm",
+            "in"
+          ],
+          "description": "Units for `width`/`height` when provided.",
+          "markdownDescription": "Units for `width`/`height` when provided.",
+          "default": "mm"
+        },
+        "margins": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "top": {
+                  "type": "string"
+                },
+                "right": {
+                  "type": "string"
+                },
+                "bottom": {
+                  "type": "string"
+                },
+                "left": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "Margins applied to the handout pages. Can be a CSS shorthand string or per-side object.",
+          "markdownDescription": "Margins applied to the handout pages. Can be a CSS shorthand string or per-side object."
+        },
+        "coverMargins": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "top": {
+                  "type": "string"
+                },
+                "right": {
+                  "type": "string"
+                },
+                "bottom": {
+                  "type": "string"
+                },
+                "left": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "Margins applied specifically to the optional cover pages.",
+          "markdownDescription": "Margins applied specifically to the optional cover pages."
+        }
+      }
+    },
+    "HandoutPredefinedSize": {
+      "type": "string",
+      "enum": [
+        "A5",
+        "A4",
+        "A3",
+        "Letter",
+        "Legal",
+        "Tabloid",
+        "Executive",
+        "a5",
+        "a4",
+        "a3",
+        "letter",
+        "legal",
+        "tabloid",
+        "executive"
+      ]
+    },
     "SeoMeta": {
       "type": "object",
       "properties": {