VitePress

VitePress is a static site generator powered by Vite and Vue. It is designed to transform Markdown files into high-performance documentation sites. Key capabilities include:

• Markdown-centric workflow: Create documentation sites primarily using Markdown.
• Vite-powered development: Benefit from instant server starts and lightning-fast Hot Module Replacement (HMR).
• Vue integration: Use Vue syntax and components directly within your Markdown files, or build entirely custom themes using Vue.
• High performance: Generates static HTML for fast initial loads and uses client-side routing for rapid post-load navigation.

VitePress is a Static Site Generator (SSG) designed for building fast, content-centric websites. It works by taking Markdown source content, applying a theme, and generating static HTML pages that can be deployed anywhere.

Key characteristics include:

• Vite-Powered: Provides instant server start and HMR (Hot Module Replacement) where edits are reflected in <100ms without full page reloads.
• Vue-Enhanced Markdown: Every Markdown page is treated as a Vue Single-File Component (SFC). This allows you to embed Vue components and use Vue templating syntax directly within your Markdown files.
• Hybrid Rendering Model: VitePress serves pre-rendered static HTML for the initial visit (optimizing SEO and initial load speed) and then hydrates into a Single Page Application (SPA) for subsequent navigations, making site transitions feel instant.

The doc layout is designed for documentation. It wraps all Markdown content within a .vp-doc CSS class and applies specific styles to generic elements like p and h2.

Note: Custom HTML added within Markdown will be affected by these documentation-specific styles.

Enabled features in doc layout:

• Edit Link
• Prev/Next navigation links
• Page Outline
• Carbon Ads

---
layout: doc
---

VitePress is suitable for several types of projects:

1. Technical Documentation: It includes a high-quality default theme optimized for documentation. It is used by major projects like Vite, Rollup, Pinia, and Vue.js.
2. Blogs, Portfolios, and Marketing Sites: Because it supports fully customized themes and provides APIs to load data (local or remote) and dynamically generate routes, it can be used for content-driven sites. As long as the data can be determined at build time, you can build almost anything.

Since it is built on Vite, you can also leverage the extensive Vite plugin ecosystem for your site.

The home layout is a specialized template for creating homepages. It supports additional frontmatter options like hero and features to build structured landing page content.

---
layout: home
---

Frontmatter allows you to override site-level or theme-level configuration options on a per-page basis within any Markdown file. You can access this data in Vue expressions using the $frontmatter global variable.

Example usage in Markdown:

---
title: Docs with VitePress
editLink: true
---

{{ $frontmatter.title }}

VitePress data loaders allow you to load arbitrary data (remote or local) at build time. The data is executed in a Node.js environment and the resulting data is serialized as JSON into the final JavaScript bundle. This means you can use Node APIs and npm dependencies (like fs or csv-parse) without shipping them to the client.

To use a data loader, create a file ending in .data.js or .data.ts and provide a default export containing a load() method. You can then import the resulting data in .md pages or .vue components using the data named export.

// example.data.js
export default {
  load() {
    return {
      hello: 'world'
    }
  }
}

// In a .vue or .md file
import { data } from './example.data.js'

In VitePress, every Markdown file is compiled into a Vue Single-File Component (SFC). This allows you to use dynamic templating, Vue components, and in-page logic via <script> tags directly within your .md files.

Key behaviors:

• Optimization: VitePress automatically optimizes static parts of the Markdown to reduce the JavaScript payload and skip client-side hydration for those parts.
• SSR Requirement: All Vue usage must be SSR-compatible. If you use browser-only APIs, wrap them in the <ClientOnly> component.
• Placement: All <script> and <style> tags must be placed after the Markdown frontmatter.

---
hello: world
---

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

## Markdown Content

<button @click="count++">Count is {{ count }}</button>

The page layout provides a "blank page" experience. While Markdown parsing and extensions still work, no default theme styling is applied to the content. This allows you to implement your own custom styling without interference from the VitePress theme.

Note: The sidebar will still appear if the page matches a sidebar configuration.

---
layout: page
---

VitePress uses a project root directory (often ./docs) to house your site.

• Source Files: Any .md files located outside the .vitepress directory are treated as source files. VitePress uses file-based routing, where each .md file is compiled into a corresponding .html file (e.g., index.md becomes /).
• .vitepress directory: A reserved directory for configuration, dev server cache, build output, and theme customization.
  • .vitepress/config.js (or .mjs/.mts): The site configuration file.
  • .vitepress/cache: Dev server cache (should be added to .gitignore).
  • .vitepress/dist: Production build output (should be added to .gitignore).

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

The useData() hook returns an object containing several reactive data sources:

• site: Contains global site configuration data.
• theme: Contains the current theme configuration and state.
• page: Contains metadata and information about the current page being rendered.
• frontmatter: Contains the key-value pairs defined in the current page's YAML frontmatter block.