Asset Handling

Learn how to manage and optimize assets in your VitePress site.

Static Assets

Public Directory

Place static assets in the public directory:

public/
├── images/
│   ├── logo.png
│   └── hero-bg.jpg
├── icons/
│   └── favicon.ico
└── downloads/
    └── guide.pdf

Referencing Public Assets

Reference public assets with absolute paths:

![Logo](/images/logo.png)
[Download Guide](/downloads/guide.pdf)

Image Optimization

Image Formats

Choose appropriate formats:

• JPEG: Photos and complex images
• PNG: Images with transparency
• WebP: Modern format with better compression
• SVG: Icons and simple graphics

Responsive Images

Use responsive image techniques:

![Hero Image](/images/hero.jpg "Hero Image")

<!-- With HTML for more control -->
<img 
  src="/images/hero-small.jpg" 
  srcset="/images/hero-small.jpg 480w, 
          /images/hero-medium.jpg 800w, 
          /images/hero-large.jpg 1200w"
  sizes="(max-width: 480px) 480px, 
         (max-width: 800px) 800px, 
         1200px"
  alt="Hero Image"
/>

Asset Processing

Vite Asset Handling

Import assets in components:

<script setup>
import logoUrl from '/images/logo.png'
import iconUrl from '/icons/icon.svg?url'
import iconInline from '/icons/icon.svg?raw'
</script>

<template>
  <img :src="logoUrl" alt="Logo" />
  <div v-html="iconInline"></div>
</template>

Asset Optimization

Configure asset optimization:

// .vitepress/config.js
export default {
  vite: {
    assetsInclude: ['**/*.pdf'],
    build: {
      assetsInlineLimit: 4096,
      rollupOptions: {
        output: {
          assetFileNames: 'assets/[name]-[hash][extname]'
        }
      }
    }
  }
}

CSS and Styling

CSS Assets

Import CSS files:

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

CSS Preprocessing

Use CSS preprocessors:

// .vitepress/config.js
export default {
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "/styles/variables.scss";`
        }
      }
    }
  }
}

Font Management

Web Fonts

Load web fonts efficiently:

/* In your CSS */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');

:root {
  --vp-font-family-base: 'Inter', sans-serif;
}

Font Optimization

Optimize font loading:

<!-- In head section -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="preload" href="/fonts/custom-font.woff2" as="font" type="font/woff2" crossorigin>

Performance Optimization

Lazy Loading

Implement lazy loading for images:

<template>
  <img 
    :src="imageSrc" 
    loading="lazy"
    alt="Description"
  />
</template>

Asset Compression

Enable compression in build:

// .vitepress/config.js
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    build: {
      minify: 'terser',
      terserOptions: {
        compress: {
          drop_console: true,
          drop_debugger: true
        }
      }
    }
  }
})

CDN Integration

External CDN

Use CDN for assets:

// .vitepress/config.js
export default {
  vite: {
    define: {
      __CDN_URL__: JSON.stringify('https://cdn.example.com')
    }
  }
}

Asset URLs

Configure asset URLs:

export default {
  base: '/my-site/',
  vite: {
    experimental: {
      renderBuiltUrl(filename, { hostType }) {
        if (hostType === 'js') {
          return `https://cdn.example.com/${filename}`
        }
        return { relative: true }
      }
    }
  }
}