创建第一个页面

现在让我们动手创建你的第一个 VitePress 页面。

创建普通页面

在 docs/ 目录下创建 hello.md 文件：

# 你好，VitePress！

这是我的第一个 VitePress 页面。

## 功能特点

- 简单易用
- 性能优异
- 功能强大

## 代码示例

\`\`\`javascript
console.log('Hello, VitePress!')
\`\`\`

访问 http://localhost:5173/hello.html 即可查看。

页面 Frontmatter

Frontmatter 是页面顶部的 YAML 配置块，用于控制页面行为：

---
title: 自定义页面标题
description: 页面描述信息
layout: doc
---

# 页面内容开始...

常用 Frontmatter 字段

字段	说明
title	页面标题（覆盖配置）
description	页面描述
layout	页面布局：doc、page、home
hero	首页英雄区域配置
features	首页特性列表
sidebar	是否显示侧边栏
outline	大纲配置

创建首页

使用 layout: home 创建一个漂亮的首页：

---
layout: home

hero:
  name: VitePress
  text: 静态站点生成器
  tagline: 简单、快速、强大
  image:
    src: /logo.svg
    alt: Logo
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/vuejs/vitepress

features:
  - title: 🚀 极速开发
    details: 基于 Vite，提供闪电般的开发体验
  - title: 📦 优化构建
    details: 自动代码分割和优化
  - title: 🎨 主题定制
    details: 灵活的主题系统和样式定制
---

Hero 配置详解

hero:
  name: 品牌名称          # 显示在 logo 下方
  text: 标题文字          # 主标题
  tagline: 标语          # 副标题
  image:
    src: /hero-image.png  # 图片路径
    alt: 图片描述
  actions:                # 按钮配置
    - theme: brand        # brand | alt
      text: 按钮文字
      link: 跳转链接

Features 配置

features:
  - title: 特性标题
    details: 特性详细描述
    icon: 🎉             # 可选图标
    link: /link          # 可选链接

使用自定义容器

VitePress 提供了几种内置的自定义容器：

提示

这是一个提示容器。

信息

这是一个信息容器。

警告

这是一个警告容器。

危险

这是一个危险容器。

详情

这是一个可折叠的详情容器。

源码：

::: tip 提示
这是一个提示容器。
:::

::: info 信息
这是一个信息容器。
:::

::: warning 警告
这是一个警告容器。
:::

::: danger 危险
这是一个危险容器。
:::

::: details 详情
这是一个可折叠的详情容器。
:::

代码块增强

语法高亮

VitePress 使用 Shiki 进行语法高亮：

// 支持 JavaScript
const greeting = 'Hello'
console.log(greeting)

// 支持 TypeScript
interface User {
  name: string
}

const user: User = { name: 'VitePress' }

行高亮

function greet(name) {
  const message = `Hello, ${name}!`  // 高亮
  console.log(message)                // 高亮
  return message
}

\`\`\`javascript{2-3}
function greet(name) {
  const message = `Hello, ${name}!`
  console.log(message)
  return message
}
\`\`\`

代码组

JavaScript

const message = 'Hello'
console.log(message)

TypeScript

const message: string = 'Hello'
console.log(message)

::: code-group

\`\`\`javascript [JavaScript]
const message = 'Hello'
\`\`\`

\`\`\`typescript [TypeScript]
const message: string = 'Hello'
\`\`\`

:::

在 Markdown 中使用 Vue

VitePress 支持在 Markdown 中直接使用 Vue 组件：

当前计数：{{ count }}

<button @click="count++">点击 +1</button>

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

下一步

恭喜你完成了第一个页面的创建！接下来让我们深入学习 Markdown 扩展语法。

常见问题

页面显示 404

检查文件路径是否正确：

• 文件必须放在 docs/ 目录下
• 路径不需要 .md 或 .html 后缀
• 确保 VitePress 开发服务器正在运行

Frontmatter 没有生效

• 确保使用 --- 包围 Frontmatter
• YAML 格式必须正确，注意缩进
• 字段名区分大小写

代码块嵌套问题

在 Markdown 中展示代码块语法时，需要使用更多反引号：

````markdown
```typescript
const greeting = 'Hello'
```
````

Vue 组件无法渲染

• 确保组件已在 .vitepress/theme/index.ts 中注册
• 检查组件名称是否与注册名称一致
• 确保没有 SSR 兼容性问题（参考 SSR 兼容性）