Merge 38b8c4dc2e into 0c434bf537

docs/.vitepress/config.ts

@@ -183,7 +183,8 @@ function sidebarReference(): DefaultTheme.SidebarItem[] {
             { text: 'Edit Link', link: 'edit-link' },
             { text: 'Last Updated Timestamp', link: 'last-updated' },
             { text: 'Search', link: 'search' },
-            { text: 'Carbon Ads', link: 'carbon-ads' }
+            { text: 'Carbon Ads', link: 'carbon-ads' },
+            { text: 'Print Pages', link: 'print-pages' }
           ]
         }
       ]

docs/.vitepress/theme/AdComponent.vue

@@ -3,10 +3,13 @@ import icon from './documate.vue'
 </script>
 
 <template>
-  <div class="ad-component">
+  <div class="ad-component screen-only">
     <a target="_blank" href="https://github.com/aircodelabs/documate">
-      <icon class="icon"/>
-      <span>Embed AI chat in your VitePress using your own content. Open-source.</span>
+      <icon class="icon" />
+      <span
+        >Embed AI chat in your VitePress using your own content.
+        Open-source.</span
+      >
       <span class="cta">Try now →</span>
     </a>
   </div>
@@ -15,7 +18,7 @@ import icon from './documate.vue'
 <style scoped>
 .ad-component {
   margin-bottom: 2rem;
-  padding: .5rem .85rem;
+  padding: 0.5rem 0.85rem;
   border: 1px solid var(--vp-c-divider);
   border-radius: 4px;
   text-decoration: none;
@@ -30,8 +33,8 @@ import icon from './documate.vue'
 
 .ad-component .icon {
   display: inline-block;
-  width: .75rem;
-  height: .75rem;
+  width: 0.75rem;
+  height: 0.75rem;
   margin-right: 0.3rem;
 }
 

docs/reference/default-theme-print-pages.md

@@ -0,0 +1,54 @@
+# Print Pages
+
+You can control what parts of the pages are printed using the `print` option. VitePress will show the whole page by default, excluding carbon-ads.
+
+Any page with Frontmatter configuration will override the global configuration, for example, the navbar will be hidden when the page containing `navbar: false`.
+
+VitePress has the `screen-only` class to hide elements when printing, you can use it in any component, html or Markdown html content.
+
+```js
+export default {
+  themeConfig: {
+    // or `print: false` to print only the main content  
+    print: {
+      outline: true,
+      navbar: true,
+      sidebar: true,
+      footer: true
+    }
+  }
+}
+```
+
+## navbar
+
+- Type: `boolean`
+
+- Details:
+
+  This flag will control the navbar visibility when printing, and will be overriden by the Frontmatter navbar option if set to `false` (navbar will not be visible).
+
+## sidebar
+
+- Type: `boolean`
+
+- Details:
+
+  This flag will control the left sidebar visibility when printing, and will be overriden by the Frontmatter sidebar option if set to `false` (sidebar will not be visible).
+
+## outline
+
+- Type: `boolean`
+
+- Details:
+
+  This flag will control the aside and outline visibility when printing, and will be overriden by the Frontmatter aside and outline options if any set to `false` (right aside will not be visible).
+
+
+## footer
+
+- Type: `boolean`
+
+- Details:
+
+  This flag will control the footer visibility when printing, and will be overriden by the Frontmatter footer option if set to `false` (footer will not be visible).

src/client/theme-default/components/VPCarbonAds.vue

@@ -106,4 +106,10 @@ if (carbonOptions) {
 .VPCarbonAds :deep(> div:first-of-type) {
   display: block;
 }
+
+@media print {
+  .VPCarbonAds {
+    display: none;
+  }
+}
 </style>

src/client/theme-default/components/VPContent.vue

@@ -5,9 +5,12 @@ import { useSidebar } from '../composables/sidebar'
 import VPDoc from './VPDoc.vue'
 import VPHome from './VPHome.vue'
 import VPPage from './VPPage.vue'
+import { useScreenOnly } from '../composables/screen-only'
 
 const { page, frontmatter } = useData()
 const { hasSidebar } = useSidebar()
+const screenOnly = useScreenOnly('navbar')
+const screenOnlySidebar = useScreenOnly('sidebar')
 </script>
 
 <template>
@@ -16,7 +19,9 @@ const { hasSidebar } = useSidebar()
     id="VPContent"
     :class="{
       'has-sidebar': hasSidebar,
-      'is-home': frontmatter.layout === 'home'
+      'is-home': frontmatter.layout === 'home',
+      'with-screen-only': screenOnly,
+      'no-print-sidebar': screenOnlySidebar
     }"
   >
     <slot name="not-found" v-if="page.isNotFound"><NotFound /></slot>
@@ -92,4 +97,14 @@ const { hasSidebar } = useSidebar()
     padding-left: calc((100vw - var(--vp-layout-max-width)) / 2 + var(--vp-sidebar-width));
   }
 }
+
+@media print {
+  .VPContent.with-screen-only:not(.is-home) {
+    --vp-nav-height: 0;
+  }
+  .VPContent.with-screen-only.no-print-sidebar {
+    padding-left: 0;
+    width: 100%;
+  }
+}
 </style>

src/client/theme-default/components/VPDoc.vue

@@ -6,11 +6,14 @@ import { useSidebar } from '../composables/sidebar'
 import VPDocAside from './VPDocAside.vue'
 import VPDocFooter from './VPDocFooter.vue'
 import VPDocOutlineDropdown from './VPDocOutlineDropdown.vue'
+import { useScreenOnly } from '../composables/screen-only'
 
 const { theme } = useData()
 
 const route = useRoute()
 const { hasSidebar, hasAside, leftAside } = useSidebar()
+const screenOnly = useScreenOnly('navbar')
+const screenOnlyOutline = useScreenOnly('outline')
 
 const pageName = computed(() =>
   route.path.replace(/[./]+/g, '_').replace(/_html$/, '')
@@ -20,11 +23,11 @@ const pageName = computed(() =>
 <template>
   <div
     class="VPDoc"
-    :class="{ 'has-sidebar': hasSidebar, 'has-aside': hasAside }"
+    :class="{ 'has-sidebar': hasSidebar, 'has-aside': hasAside, 'with-screen-only': screenOnly }"
   >
     <slot name="doc-top" />
     <div class="container">
-      <div v-if="hasAside" class="aside" :class="{'left-aside': leftAside}">
+      <div v-if="hasAside" class="aside" :class="{'left-aside': leftAside,'screen-only': screenOnlyOutline}">
         <div class="aside-curtain" />
         <div class="aside-container">
           <div class="aside-content">
@@ -207,4 +210,13 @@ const pageName = computed(() =>
   content: '';
   color: currentColor;
 }
+
+@media print {
+  .VPDoc.with-screen-only {
+    padding-top: 24px !important;
+  }
+  .VPDoc.has-aside.with-screen-only .content-container {
+    max-width: unset;
+  }
+}
 </style>

src/client/theme-default/components/VPDocOutlineDropdown.vue

@@ -5,8 +5,11 @@ import { getHeaders, resolveTitle, type MenuItem } from '../composables/outline'
 import VPDocOutlineItem from './VPDocOutlineItem.vue'
 import { onContentUpdated } from 'vitepress'
 import VPIconChevronRight from './icons/VPIconChevronRight.vue'
+import { useScreenOnly } from '../composables/screen-only'
 
 const { frontmatter, theme } = useData()
+const screenOnly = useScreenOnly('navbar')
+
 const open = ref(false)
 
 onContentUpdated(() => {
@@ -14,7 +17,6 @@ onContentUpdated(() => {
 })
 
 const headers = shallowRef<MenuItem[]>([])
-
 onContentUpdated(() => {
   headers.value = getHeaders(
     frontmatter.value.outline ?? theme.value.outline
@@ -23,7 +25,7 @@ onContentUpdated(() => {
 </script>
 
 <template>
-  <div class="VPDocOutlineDropdown" v-if="headers.length > 0">
+  <div v-if="headers.length > 0" class="VPDocOutlineDropdown" :class="{ 'screen-only': screenOnly }">
     <button @click="open = !open" :class="{ open }">
       {{ resolveTitle(theme) }}
       <VPIconChevronRight class="icon" />

src/client/theme-default/components/VPFooter.vue

@@ -1,13 +1,19 @@
 <script setup lang="ts">
 import { useData } from '../composables/data'
 import { useSidebar } from '../composables/sidebar'
+import { useScreenOnly } from '../composables/screen-only'
 
 const { theme, frontmatter } = useData()
 const { hasSidebar } = useSidebar()
+const screenOnly = useScreenOnly('footer')
 </script>
 
 <template>
-  <footer v-if="theme.footer && frontmatter.footer !== false" class="VPFooter" :class="{ 'has-sidebar': hasSidebar }">
+  <footer
+    v-if="theme.footer && frontmatter.footer !== false"
+    class="VPFooter"
+    :class="{ 'has-sidebar': hasSidebar, 'screen-only': screenOnly }"
+  >
     <div class="container">
       <p v-if="theme.footer.message" class="message" v-html="theme.footer.message"></p>
       <p v-if="theme.footer.copyright" class="copyright" v-html="theme.footer.copyright"></p>

src/client/theme-default/components/VPLocalNav.vue

@@ -7,6 +7,7 @@ import { getHeaders, type MenuItem } from '../composables/outline'
 import { useSidebar } from '../composables/sidebar'
 import VPLocalNavOutlineDropdown from './VPLocalNavOutlineDropdown.vue'
 import VPIconAlignLeft from './icons/VPIconAlignLeft.vue'
+import { useScreenOnly } from '../composables/screen-only'
 
 defineProps<{
   open: boolean
@@ -39,11 +40,14 @@ const empty = computed(() => {
   return headers.value.length === 0 && !hasSidebar.value
 })
 
+const screenOnly = useScreenOnly('navbar')
+
 const classes = computed(() => {
   return {
     VPLocalNav: true,
     fixed: empty.value,
-    'reached-top': y.value >= navHeight.value
+    'reached-top': y.value >= navHeight.value,
+    'screen-only': screenOnly.value
   }
 })
 </script>

src/client/theme-default/components/VPNav.vue

@@ -5,9 +5,11 @@ import { useData } from '../composables/data'
 import { useNav } from '../composables/nav'
 import VPNavBar from './VPNavBar.vue'
 import VPNavScreen from './VPNavScreen.vue'
+import {useScreenOnly} from "../composables/screen-only";
 
 const { isScreenOpen, closeScreen, toggleScreen } = useNav()
 const { frontmatter } = useData()
+const screenOnly = useScreenOnly('navbar')
 
 const hasNavbar = computed(() => {
   return frontmatter.value.navbar !== false
@@ -23,7 +25,7 @@ watchEffect(() => {
 </script>
 
 <template>
-  <header v-if="hasNavbar" class="VPNav">
+  <header v-if="hasNavbar" class="VPNav" :class="{ 'screen-only': screenOnly }">
     <VPNavBar :is-screen-open="isScreenOpen" @toggle-screen="toggleScreen">
       <template #nav-bar-title-before><slot name="nav-bar-title-before" /></template>
       <template #nav-bar-title-after><slot name="nav-bar-title-after" /></template>

src/client/theme-default/components/VPSidebar.vue

@@ -4,8 +4,10 @@ import { inBrowser } from 'vitepress'
 import { ref, watch } from 'vue'
 import { useSidebar } from '../composables/sidebar'
 import VPSidebarItem from './VPSidebarItem.vue'
+import { useScreenOnly } from '../composables/screen-only'
 
 const { sidebarGroups, hasSidebar } = useSidebar()
+const screenOnly = useScreenOnly('sidebar')
 
 const props = defineProps<{
   open: boolean
@@ -31,7 +33,7 @@ watch(
   <aside
     v-if="hasSidebar"
     class="VPSidebar"
-    :class="{ open }"
+    :class="{ open, 'screen-only': screenOnly }"
     ref="navEl"
     @click.stop
   >

src/client/theme-default/composables/screen-only.ts

@@ -0,0 +1,18 @@
+import { useData } from './data'
+import type { DefaultTheme } from 'vitepress/theme'
+import { computed } from 'vue'
+
+export function useScreenOnly(entry: keyof DefaultTheme.PrintOptions) {
+  const { theme, frontmatter } = useData()
+
+  // we have aside and outline in frontmatter, we will check for both for outline
+  return computed(
+    () =>
+      (entry === 'outline'
+        ? frontmatter.value.aside === false ||
+          frontmatter.value.outline === false
+        : frontmatter.value[entry] === false) ||
+      theme.value.print === false ||
+      theme.value.print![entry] === false
+  )
+}

src/client/theme-default/styles/utils.css

@@ -7,3 +7,9 @@
   clip-path: inset(50%);
   overflow: hidden;
 }
+
+@media print {
+  .screen-only {
+    display: none !important;
+  }
+}

src/node/config.ts

@@ -236,6 +236,16 @@ export async function resolveSiteData(
 ): Promise<SiteData> {
   userConfig = userConfig || (await resolveUserConfig(root, command, mode))[0]
 
+  const themeConfig = userConfig.themeConfig || {}
+
+  if (typeof themeConfig.print !== 'boolean') {
+    themeConfig.print ??= {}
+    themeConfig.print.outline ??= true
+    themeConfig.print.navbar ??= true
+    themeConfig.print.sidebar ??= true
+    themeConfig.print.footer ??= true
+  }
+
   return {
     lang: userConfig.lang || 'en-US',
     dir: userConfig.dir || 'ltr',
@@ -248,7 +258,7 @@ export async function resolveSiteData(
       prefetchLinks: userConfig.router?.prefetchLinks ?? true
     },
     appearance: userConfig.appearance ?? true,
-    themeConfig: userConfig.themeConfig || {},
+    themeConfig,
     locales: userConfig.locales || {},
     scrollOffset: userConfig.scrollOffset ?? 90,
     cleanUrls: !!userConfig.cleanUrls,

types/default-theme.d.ts

@@ -145,6 +145,17 @@ export namespace DefaultTheme {
      * Customize text of 404 page.
      */
     notFound?: NotFoundOptions
+
+    /**
+     * Customize how pages will be printed.
+     *
+     * To exclude `outline`, `navbar`, `sidebar` and `footer` from being printed, configure `print: false`.
+     *
+     * Frontmatter configuration will override the global configuration, for example, a page containing `navbar: false`, the navbar will not be printed.
+     *
+     * @default { outline: true, navbar: true, sidebar: true, footer: true }
+     */
+    print?: false | PrintOptions
   }
 
   // nav -----------------------------------------------------------------------
@@ -474,4 +485,33 @@ export namespace DefaultTheme {
      */
     code?: string
   }
+
+  // print options -----------------------------------------------------------------
+
+  export interface PrintOptions {
+    /**
+     * Should the outline be printed?
+     *
+     * @default true
+     */
+    outline?: boolean
+    /**
+     * Should the navbar be printed?
+     *
+     * @default true
+     */
+    navbar?: boolean
+    /**
+     * Should the sidebar be printed?
+     *
+     * @default true
+     */
+    sidebar?: boolean
+    /**
+     * Should the footer be printed?
+     *
+     * @default true
+     */
+    footer?: boolean
+  }
 }