---
url: /guide/getting-started.md
---
# Getting Started

This guide demonstrates the features pre-configured in this template.

## Code Groups with Icons

::: code-group

```js [config.js]
export default {
  title: 'My App',
  description: 'My app description',
}
```

```ts [config.ts]
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My App',
  description: 'My app description',
})
```

```bash [install.sh]
pnpm install
pnpm docs:dev
```

:::

## Mermaid Diagrams

```mermaid
flowchart LR
  A[Start] --> B{Is it working?}
  B -->|Yes| C[Done]
  B -->|No| D[Debug]
  D --> A
```

```mermaid
sequenceDiagram
  participant U as User
  participant D as Docs
  U->>D: Search for topic
  D->>U: Return results
  U->>D: Click link
  D->>U: Show page
```

## Image Zoom

Click the image below to see the zoom effect.

![Sample Image](https://placehold.co/800x400/42b883/ffffff?text=Click+to+Zoom)

## Local Search

This template comes with built-in full-text local search. Press `Ctrl+K` (or `Cmd+K` on Mac) to open the search dialog and try it now.

## Math Equations (optional)

If you need math support, add `markdown-it-mathjax3` to your dependencies and configure it in `config.ts`.

## Customization

1. Replace `YOUR_REPO` placeholders in `config.ts` and `deploy.yml` with your actual GitHub repo.
2. Set up your Giscus comment configuration in `GiscusComment.vue`.
3. Customize the logo by replacing `docs/.vitepress/public/logo.svg`.
4. Add your own pages under the `docs/` directory.

---

---
url: /java/springboot.md
---
# Spring Boot Notes

Spring Boot makes it easy to create stand-alone, production-grade Spring-based applications.

## Quick Start

```bash
# Create a new Spring Boot project
curl https://start.spring.io/starter.zip -d type=maven-project \
  -d language=java -d bootVersion=3.4.0 \
  -d groupId=com.example -d artifactId=demo \
  -o demo.zip
```

## Project Structure

```md
src/
├── main/
│   ├── java/com/example/demo/
│   │   ├── DemoApplication.java
│   │   ├── controller/
│   │   └── service/
│   └── resources/
│       └── application.yml
└── test/
```

## Common Annotations

| Annotation | Purpose |
|---|---|
| `@SpringBootApplication` | Entry point of a Spring Boot app |
| `@RestController` | RESTful controller |
| `@RequestMapping` | Map web requests |
| `@Autowired` | Dependency injection |
| `@Service` | Service layer component |
| `@Repository` | Data access layer component |

## REST Example

```java
@RestController
@RequestMapping("/api/todos")
public class TodoController {

    @GetMapping
    public List<Todo> getAll() {
        return todoService.findAll();
    }

    @PostMapping
    public Todo create(@RequestBody Todo todo) {
        return todoService.save(todo);
    }
}
```

---

---
url: /ai/llm.md
---
# LLM Basics

Large Language Models (LLMs) are deep learning models trained on massive text datasets.

## Model Architecture

```mermaid
graph TD
    subgraph Training
        A[Text Corpus] --> B[Tokenization]
        B --> C[Transformer Model]
        C --> D[Next Token Prediction]
    end
    subgraph Inference
        E[Prompt] --> F[Tokenization]
        F --> G[Transformer Forward Pass]
        G --> H[Generate Next Token]
        H --> I{Stop Condition}
        I -->|No| G
        I -->|Yes| J[Output Text]
    end
```

## Popular Models

| Model | Provider | Open Source | Key Feature |
|---|---|---|---|
| GPT-4o | OpenAI | No | Multimodal, fast |
| Claude 3.5 Sonnet | Anthropic | No | Long context, code |
| Llama 3 | Meta | Yes | Open weights |
| DeepSeek-V3 | DeepSeek | Yes | Strong reasoning |

## Prompt Engineering Tips

1. **Be specific** — vague prompts get vague answers
2. **Provide context** — give the model relevant background
3. **Use examples** — few-shot prompting improves accuracy
4. **Chain of thought** — ask the model to think step by step
5. **Set constraints** — limit length, format, or tone

## Tokenization

```python
# Example: counting tokens
import tiktoken

enc = tiktoken.get_encoding("cl100k_base")
tokens = enc.encode("Hello, how are you?")
print(f"Token count: {len(tokens)}")
print(f"Tokens: {tokens}")
```

---

---
url: /showcase/markdown.md
description: 列举 VitePress 支持的标准 Markdown 语法，每个示例含语法说明、写法与实际效果
---

# Markdown 格式示例

本页集中展示 VitePress 支持的\*\*标准 Markdown（CommonMark / GFM）\*\*语法。

> 每个示例都按三部分呈现：**语法说明**（是什么 / 怎么用）→ **示例写法**（原始 Markdown 源码）→ **实际效果**（渲染后的样子）。

## 1. 标题

**语法说明**：用 `#` ~ `######` 表示一级到六级标题，井号数量对应层级。

**示例写法**：

```md
# 一级标题 H1
## 二级标题 H2
### 三级标题 H3
#### 四级标题 H4
##### 五级标题 H5
###### 六级标题 H6
```

**实际效果**：

# 一级标题 H1

## 二级标题 H2

### 三级标题 H3

#### 四级标题 H4

##### 五级标题 H5

###### 六级标题 H6

## 2. 文本样式

**语法说明**：星号 / 波浪号 / 等号包裹文本实现加粗、斜体、删除线、高亮等样式。

**示例写法**：

```md
**加粗**  *斜体*  ***加粗斜体***  ~~删除线~~  ==高亮==
```

**实际效果**：

**加粗**  *斜体*  ***加粗斜体***  ~~删除线~~  ==高亮==

## 3. 行内代码

**语法说明**：用反引号包裹表示行内代码，不会被渲染为格式。

**示例写法**：

```md
使用 `pnpm install` 安装依赖，再执行 `pnpm docs:dev` 启动。
```

**实际效果**：

使用 `pnpm install` 安装依赖，再执行 `pnpm docs:dev` 启动。

## 4. 上下标

**语法说明**：用 `~` 包裹下标、`^` 包裹上标（VitePress 基于 markdown-it-sub / sup 支持）。

**示例写法**：

```md
水的化学式 H~2~O，质能方程 E = mc^2^。
```

**实际效果**：

水的化学式 H~2~O，质能方程 E = mc^2^。

## 5. 键盘按键

**语法说明**：用 HTML 的 `<kbd>` 标签渲染键盘按键样式。

**示例写法**：

```md
按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 唤起全站搜索。
```

**实际效果**：

按 Ctrl + K 唤起全站搜索。

## 6. 段落与换行

**语法说明**：段落之间空一行分隔；行尾加两个空格再换行是「软换行」（同一段内换行）。

**示例写法**：

```md
这是第一段。

这是第二段（中间空一行）。

软换行在行尾加两个空格  
来实现。
```

**实际效果**：

这是第一段。

这是第二段（中间空一行）。

软换行在行尾加两个空格\
来实现。

## 7. 引用

**语法说明**：用 `>` 开头表示引用块，`>` 后接空行再 `>` 可实现嵌套引用。

**示例写法**：

```md
> 外层引用
>
> > 内层引用（嵌套）
```

**实际效果**：

> 外层引用
>
> > 内层引用（嵌套）

## 8. 列表

**语法说明**：`-` / `*` 表示无序列表，`1.` 表示有序列表；缩进两格表示嵌套。

**示例写法**：

```md
- 水果
  - 苹果
  - 香蕉
- 蔬菜

1. 第一步
2. 第二步
   1. 子步骤
```

**实际效果**：

* 水果
  * 苹果
  * 香蕉
* 蔬菜

1. 第一步
2. 第二步
   1. 子步骤

## 9. 任务列表

**语法说明**：在列表项前用 `[ ]`（未完成）或 `[x]`（已完成）表示复选框，GFM 扩展语法。

**示例写法**：

```md
- [x] 已完成任务
- [ ] 未完成任务
- [ ] 待办事项
```

**实际效果**：

* \[x] 已完成任务
* \[ ] 未完成任务
* \[ ] 待办事项

## 10. 定义列表

**语法说明**：术语单独一行，下一行用 `:` 开头给出定义；多个 `:` 行表示多个含义。

**示例写法**：

```md
Markdown
: 轻量级标记语言。

VitePress
: 基于 Vite 的静态站点生成器。
: 专为文档场景设计。
```

**实际效果**：

Markdown
: 轻量级标记语言。

VitePress
: 基于 Vite 的静态站点生成器。
: 专为文档场景设计。

## 11. 代码块

**语法说明**：用三个反引号包裹，并标注语言即可获得语法高亮；不带语言则为纯文本。

**示例写法**：

````md
```ts
interface User {
  id: number
  name: string
}

function greet(user: User): string {
  return `Hello, ${user.name}!`
}
```
````

**实际效果**：

```ts
interface User {
  id: number
  name: string
}

function greet(user: User): string {
  return `Hello, ${user.name}!`
}
```

## 12. 表格

**语法说明**：用 `|` 分隔列，第二行用 `-` 画分隔线；冒号控制对齐方式（`:---` 左、`---:` 右、`:---:` 中）。

**示例写法**：

```md
| 名称   | 类型   | 是否推荐 |
| :----- | :----: | -------: |
| 苹果   | 水果   |      是 |
| 胡萝卜 | 蔬菜   |      是 |
```

**实际效果**：

| 名称   | 类型   | 是否推荐 |
| :----- | :----: | -------: |
| 苹果   | 水果   |      是 |
| 胡萝卜 | 蔬菜   |      是 |

## 13. 链接

**语法说明**：`[文本](地址)` 创建链接；支持外部地址、站内绝对路径、锚点（`#标题`）、邮件 `mailto:`；也可用原生 HTML 控制新窗口打开。

**示例写法**：

```md
- 外部：[VitePress 官网](https://vitepress.dev)
- 站内：[/guide/getting-started](/guide/getting-started)
- 锚点：[跳到「表格」](#12-表格)
- 邮件：[发送邮件](mailto:hello@example.com)
- 新窗口：<a href="https://vitepress.dev" target="_blank">VitePress（新窗口）</a>
```

**实际效果**：

* 外部：[VitePress 官网](https://vitepress.dev)
* 站内：[/guide/getting-started](/guide/getting-started)
* 锚点：[跳到「表格」](#12-表格)
* 邮件：[发送邮件](mailto:hello@example.com)
* 新窗口：VitePress（新窗口）

## 14. 图片

**语法说明**：`![替代文本](路径)` 插入图片。本文档图片放在同目录，用相对路径 `./logo.svg` 引用；放在 `docs/.vitepress/public/` 的资源则用 `/logo.svg` 引用。点击图片可放大（参见「插件应用示例」页的 medium-zoom），加 `.no-zoom` 类可禁用缩放。

**示例写法**：

```md
![Logo](/logo.svg)

![不缩放的 Logo](/logo.svg){.no-zoom}
```

**实际效果**（下图可点击放大，本页已接入 medium-zoom）：

![Logo](./logo.svg)

## 15. 脚注

**语法说明**：正文用 `[^标签]`，文末用 `[^标签]: 解释` 定义脚注，GFM 扩展语法。

> ⚠️ 注意：VitePress 默认未内置脚注插件。下方仅展示语法，需安装 `markdown-it-footnote` 并在 `markdown.config` 中调用 `md.use(footnote)` 后才会真正渲染到页面底部。

**示例写法**：

```md
这是带脚注的句子。[^1] 还有另一个引用。[^note]

[^1]: 脚注内容一，出现在页面底部。
[^note]: 脚注内容二，标签可为任意字母数字。
```

## 16. 表情符号（Emoji 短码）

**语法说明**：用 `:短码:` 插入表情，VitePress 内置 emoji 支持。

**示例写法**：

```md
:rocket: :sparkles: :warning: :heart: :tada:
```

**实际效果**：

:rocket: :sparkles: :warning: :heart: :tada:

## 17. 水平分割线

**语法说明**：单独一行的三个或以上连字符 `---` 渲染为分隔线。

**示例写法**：

```md
上方内容

---

下方内容
```

**实际效果**：

上方内容

***

下方内容

## 18. 转义字符

**语法说明**：用反斜杠 `\` 转义 Markdown 特殊字符，使其按原样显示。

**示例写法**：

```md
\*这不是斜体\*，\#这不是标题，\`这不是代码\`。
```

**实际效果**：

\*这不是斜体\*，#这不是标题，\`这不是代码\`。

## 19. 原生 HTML

**语法说明**：Markdown 中可直接书写 HTML，可借助内联样式实现任意排版。

**示例写法**：

```md
这是 <strong>加粗的原生 HTML</strong>。

<div style="padding:8px 12px;border:1px dashed var(--vp-c-border);border-radius:8px;">
用原生 HTML 渲染的内容，可使用任意内联样式。
</div>
```

**实际效果**：

这是 加粗的原生 HTML。

## 20. 注释

**语法说明**：HTML 注释 `<!-- -->` 只在源码中可见，不会被渲染到页面。

**示例写法**：

```md
<!-- 这是一段注释，读者看不到 -->
```

**实际效果**（下面整行不会显示任何内容）：

## 21. 字符实体

**语法说明**：HTML 字符实体可用于显示特殊符号，如 `&amp;`、`&lt;`、`&copy;`。

**示例写法**：

```md
&copy; 2026 &amp; &lt;tag&gt; &nbsp;不换行空格
```

**实际效果**：

© 2026 & \<tag>  不换行空格

---

---
url: /showcase/plugins.md
description: 已安装的各款 VitePress 插件，每个含语法说明、写法与实际效果
---

# 插件应用示例

本模板已预装多款插件。本页逐一演示它们的**实际效果**与基本用法。

> 每个插件按三部分呈现：**语法说明** → **示例写法**（配置 / 源码）→ **实际效果**（页面上的真实表现）。

## 1. Mermaid 图表

**语法说明**：由 `vitepress-plugin-mermaid` 提供，用 ` ```mermaid ` 代码块即可绘制图表，支持 flowchart / sequence / gantt / class / state / pie 等多种图。在 `config.ts` 中通过 `withMermaid(defineConfig({...}))` 启用。

### 流程图

**示例写法**：

````md
```mermaid
flowchart LR
  A[开始] --> B{是否登录?}
  B -->|是| C[进入控制台]
  B -->|否| D[跳转登录]
  D --> C
  C --> E[结束]
```
````

**实际效果**：

```mermaid
flowchart LR
  A[开始] --> B{是否登录?}
  B -->|是| C[进入控制台]
  B -->|否| D[跳转登录]
  D --> C
  C --> E[结束]
```

### 时序图

**示例写法**：

````md
```mermaid
sequenceDiagram
  participant U as 用户
  participant B as 浏览器
  participant S as 服务器
  U->>B: 点击按钮
  B->>S: 发送请求
  S-->>B: 返回 JSON
  B-->>U: 渲染页面
```
````

**实际效果**：

```mermaid
sequenceDiagram
  participant U as 用户
  participant B as 浏览器
  participant S as 服务器
  U->>B: 点击按钮
  B->>S: 发送请求
  S-->>B: 返回 JSON
  B-->>U: 渲染页面
```

### 甘特图

**示例写法**：

````md
```mermaid
gantt
  title 文档站建设计划
  dateFormat YYYY-MM-DD
  section 搭建
  初始化模板   :done,   a1, 2026-01-01, 3d
  配置部署     :active, a2, after a1, 4d
  section 内容
  编写文档     :        a3, after a2, 7d
```
````

**实际效果**：

```mermaid
gantt
  title 文档站建设计划
  dateFormat YYYY-MM-DD
  section 搭建
  初始化模板   :done,   a1, 2026-01-01, 3d
  配置部署     :active, a2, after a1, 4d
  section 内容
  编写文档     :        a3, after a2, 7d
```

### 类图 / 状态图 / 饼图

**示例写法**：

````md
```mermaid
classDiagram
  class Doc {
    +title: string
    +render()
  }
  class Page {
    +path: string
  }
  Doc <|-- Page
```

```mermaid
stateDiagram-v2
  [*] --> 草稿
  草稿 --> 评审: 提交
  评审 --> 发布: 通过
  发布 --> [*]
```

```mermaid
pie title 构建产物占比
  "JS" : 45
  "CSS" : 25
  "HTML" : 20
  "其他" : 10
```
````

**实际效果**：

```mermaid
classDiagram
  class Doc {
    +title: string
    +render()
  }
  class Page {
    +path: string
  }
  Doc <|-- Page
```

```mermaid
stateDiagram-v2
  [*] --> 草稿
  草稿 --> 评审: 提交
  评审 --> 发布: 通过
  发布 --> [*]
```

```mermaid
pie title 构建产物占比
  "JS" : 45
  "CSS" : 25
  "HTML" : 20
  "其他" : 10
```

## 2. 图片缩放（medium-zoom）

**语法说明**：`medium-zoom` 已接入主题，文档正文中的图片点击即可放大查看；加 `.no-zoom` 类可禁用某张图片的缩放。

**示例写法**：

```md
![Logo 放大预览](/logo.svg)

![不缩放的 Logo](/logo.svg){.no-zoom}
```

**实际效果**（点击下方 Logo 试试放大，本仓库已接入 medium-zoom）：

![Logo 放大预览](./logo.svg)

## 3. 评论系统（Giscus）

**语法说明**：`@giscus/vue` 已在主题组件 `GiscusComment.vue` 中以 `doc-after` 位置自动注入，每篇文档底部显示由 GitHub Discussions 驱动的评论区（首页除外）。使用前需在组件中替换占位符，并在仓库安装 [Giscus](https://giscus.app) 应用、开启 Discussions。

**示例写法**（`docs/.vitepress/theme/components/GiscusComment.vue` 中的配置项）：

```ts
<Giscus
  repo="YOUR_REPO/YOUR_REPO"      // 改为你的 "owner/repo"
  repoId="YOUR_REPO_ID"           // Giscus 返回的 repoId
  category="Announcements"
  categoryId="YOUR_CATEGORY_ID"   // 分类 ID
  mapping="pathname"
  theme="preferred_color_scheme"
  lang="en"
/>
```

**实际效果**：本页底部即由该组件渲染的评论区（若尚未配置 GitHub 凭据，则会显示加载失败或空白，属正常——配置后生效）。

## 4. 代码组文件图标（group-icons）

**语法说明**：`vitepress-plugin-group-icons` 已启用（`config.ts` 中 `markdown.codeTransformers: [groupIconMdPlugin]`），带文件名标注（`[文件名]`）的代码块会自动显示对应语言 / 文件图标。

**示例写法**：

````md
```ts [utils.ts]
export const sum = (a: number, b: number) => a + b
```

```json [config.json]
{ "name": "demo" }
```

```vue [Button.vue]
<template>
  <button class="btn">{{ label }}</button>
</template>
```
````

**实际效果**（每个代码块标题左侧应显示对应文件图标）：

```ts [utils.ts]
export const sum = (a: number, b: number) => a + b
```

```json [config.json]
{ "name": "demo", "version": "1.0.0" }
```

```vue [Button.vue]
<template>
  <button class="btn">{{ label }}</button>
</template>
```

## 5. PWA（vite-plugin-pwa）

**语法说明**：`vite-plugin-pwa` 在 `docs/.vitepress/vite-plugins/pwa.ts` 中配置，`buildEnd` 时生成 Service Worker 与 `manifest.webmanifest`，使站点可「安装为应用」并离线访问。

**示例写法**（核心配置）：

```ts
VitePWA({
  registerType: 'autoUpdate',
  manifest: {
    name: 'My Docs',
    short_name: 'My Docs',
    theme_color: '#ffffff',
    icons: [{ src: 'logo.svg', sizes: '192x192', type: 'image/svg+xml' }],
  },
  includeAssets: ['logo.svg'],
})
```

**实际效果**：部署后访问站点，浏览器地址栏会出现「安装」按钮；断网后仍可阅读已缓存页面（本模板已配置 `registerType: 'autoUpdate'`）。

## 6. Sitemap（sitemap）

**语法说明**：`docs/.vitepress/vite-plugins/sitemap.ts` 在 `buildEnd` 阶段扫描 `dist` 下所有 HTML，生成 `sitemap.xml`，便于搜索引擎收录。

**示例写法**（核心逻辑）：

```ts
export function generateSitemap(siteUrl = 'https://YOUR_REPO.github.io/YOUR_REPO/') {
  // 扫描 dist/*.html -> 写入 sitemap.xml
}
```

**实际效果**：默认站点地址占位为 `https://YOUR_REPO.github.io/YOUR_REPO/`，**上线前请替换为真实域名**；生成的 `sitemap.xml` 位于构建产物根目录，可直接被爬虫发现。

## 7. 日期工具（dayjs）

**语法说明**：`dayjs` 是轻量日期库，作为工具依赖预装在本模板中。它并非「文档渲染插件」，而是供主题或自定义组件处理时间显示（例如把 `lastUpdated` 时间戳格式化为本地化文案）。

**示例写法**：

```ts
import dayjs from 'dayjs'

dayjs().format('YYYY-MM-DD HH:mm')        // 当前时间
dayjs('2026-01-01').fromNow()             // 需引入 relativeTime 插件
```

> 说明：截至当前版本，`dayjs` 已预装但尚未在主题中实际接入 `lastUpdated` 格式化，因此页面上暂无直接可见效果，这里仅展示用法。如需启用，可在 `theme/index.ts` 中 `import dayjs` 并改写时间显示逻辑。

## 小结

| 插件                          | 作用                  | 本页演示                       |
| ----------------------------- | --------------------- | ------------------------------ |
| `vitepress-plugin-mermaid`    | 图表渲染              | 流程图 / 时序 / 甘特 / 类 / 状态 / 饼图 |
| `medium-zoom`                 | 图片点击放大          | 上方 Logo 可点击               |
| `@giscus/vue`                 | 文档评论              | 页面底部评论区                 |
| `vitepress-plugin-group-icons` | 代码块文件图标       | 上方带文件名代码块             |
| `vite-plugin-pwa`             | 离线 / 可安装 PWA     | 安装按钮 + 离线缓存            |
| `sitemap`                     | 生成 sitemap.xml      | 构建产物中查看                 |
| `dayjs`                       | 日期处理工具          | 代码片段（尚未接入主题）       |

---

---
url: /showcase/vitepress.md
description: 展示 VitePress 专属扩展格式，每个示例含语法说明、写法与实际效果
---

# VitePress 文档格式示例

本页展示 VitePress 在 Markdown 之上的**专属扩展格式**——这些写法在标准 Markdown 中不存在，是 VitePress 提供的增强能力。

> 每个示例都按三部分呈现：**语法说明** → **示例写法**（原始源码）→ **实际效果**（渲染结果）。

## 1. 自定义容器（提示框）

**语法说明**：以 `::: 类型` 开头、`:::` 结尾即可创建语义化提示框。常用类型：`tip`、`info`、`warning`、`danger`；`details` 为可折叠容器，类型后可跟标题文字。

**示例写法**：

````md
::: tip 提示
这是 `tip` 容器，用于友好的提示信息。
:::

::: warning 警告
这是 `warning` 容器，用于需要注意的事项。
:::

::: details 点击展开查看更多
这是可折叠容器，默认收起，点击标题展开。可放任意内容，包括代码：

```ts
console.log("折叠区域内的代码")
```
:::
````

**实际效果**：

::: tip 提示
这是 `tip` 容器，用于友好的提示信息。
:::

::: info 信息
这是 `info` 容器，用于补充说明。
:::

::: warning 警告
这是 `warning` 容器，用于需要注意的事项。
:::

::: danger 危险
这是 `danger` 容器，用于严重警告。
:::

::: details 点击展开查看更多
这是 `details` 可折叠容器，默认收起，点击标题展开。可以放任意内容，包括代码：

```ts
console.log("折叠区域内的代码")
```

:::

## 2. 徽章（Badge）

**语法说明**：行内徽章用 `:badge[文字]{.样式}` 表示，可用样式有 `.info`、`.tip`、`.warning`、`.danger`。

**示例写法**：

```md
新功能 :badge[NEW]{.info}、实验性 :badge[beta]{.warning}、已废弃 :badge[deprecated]{.danger}
```

**实际效果**：

新功能 :badge\[NEW]{.info}、实验性 :badge\[beta]{.warning}、已废弃 :badge\[deprecated]{.danger}

## 3. 代码组（多标签切换）

**语法说明**：`::: code-group` 把多个同义代码块以标签页形式切换，常用于不同包管理器的命令。代码块语言后的方括号文字 `[标签]` 显示为选项卡标题；带文件名标注时还会配合 group-icons 显示图标（见「插件应用示例」页）。

**示例写法**：

````md
::: code-group

```bash [npm]
npm install vitepress
```

```bash [pnpm]
pnpm add vitepress
```

```bash [yarn]
yarn add vitepress
```

:::
````

**实际效果**：

::: code-group

```bash [npm]
npm install vitepress
```

```bash [pnpm]
pnpm add vitepress
```

```bash [yarn]
yarn add vitepress
```

:::

## 4. 代码块增强

### 4.1 行高亮

**语法说明**：在代码块语言后加 `{行号}`（如 `{2,4-5}`）高亮指定行。

**示例写法**：

````md
```ts {2,4-5}
function demo() {
  const a = 1      // 高亮
  const b = 2
  const c = 3      // 高亮
  const d = 4      // 高亮
}
```
````

**实际效果**：

```ts {2,4-5}
function demo() {
  const a = 1      // 高亮
  const b = 2
  const c = 3      // 高亮
  const d = 4      // 高亮
}
```

### 4.2 行号

**语法说明**：在代码块语言后加 `showLineNumbers` 显示行号。

**示例写法**：

````md
```ts showLineNumbers
console.log(1)
console.log(2)
console.log(3)
```
````

**实际效果**：

```ts showLineNumbers
console.log(1)
console.log(2)
console.log(3)
```

### 4.3 Diff 高亮

**语法说明**：在代码块语言后加 `{diff}`，配合 `-` / `+` 前缀高亮删除与新增行。

**示例写法**：

````md
```ts {diff}
- const old = 1
+ const now = 2
```
````

**实际效果**：

```ts {diff}
- const old = 1
+ const now = 2
```

## 5. 从文件导入代码片段

**语法说明**：用 `<<< @/相对路径` 可直接把某个源文件嵌入文档，`@` 指向文档源目录（本项目为 `docs/`）。适合展示真实、可维护的示例代码。

**示例写法**（导入本仓库的 `README.md` 前 5 行）：

```md
<<< @/../README.md {1-5}
```

**实际效果**（展示 `README.md` 的前 5 行）：

````md {1-5}
# VitePress Template

A ready-to-use VitePress documentation site template with popular plugins pre-configured.

## Features

- **Full-text local search** — press `Ctrl+K` to search
- **Mermaid diagrams** — draw flowcharts, sequence diagrams, and more
- **Image zoom** — click to enlarge images
- **PWA support** — install as a progressive web app
- **Sitemap generation** — auto-generated `sitemap.xml` for SEO
- **Open Graph & Twitter Cards** — SEO meta tags included
- **Giscus comments** — GitHub Discussions powered comments
- **Code group icons** — automatic file-type icons in code tabs
- **Markmap mind maps** — render interactive mind maps from Markdown outlines
- **Tabs** — group content into tabbed panels
- **Demo preview** — live-render Vue/React/HTML demos with source
- **Auto sidebar** — sidebar generated from the file tree
- **NProgress** — top loading bar on route change
- **llms.txt** — auto-generate `llms.txt` / `llms-full.txt` for AI crawlers
- **RSS feed** — auto-generate `feed.rss`
- **GitHub Actions deploy** — one config file controls deploy to GitHub Pages / Cloudflare Pages / Vercel / Netlify
- **Custom 404 page** — built-in

## Quick Start

```bash
# 1. Clone the template
git clone https://github.com/YOUR_REPO/vitepress-template.git my-docs
cd my-docs

# 2. Install dependencies
pnpm install

# 3. Start the dev server
pnpm docs:dev
```

## Customization

1. **Site config** — edit `docs/.vitepress/config.ts`
2. **Navigation** — update `themeConfig.nav` and `themeConfig.sidebar`
3. **Logo** — replace `docs/.vitepress/public/logo.svg`
4. **GitHub repo** — replace `YOUR_REPO` placeholders in `config.ts`
5. **Deployment** — edit `.github/deploy-config.yaml` to set Node/pnpm versions and toggle target platforms (`github-pages` / `cloudflare` / `vercel` / `netlify`). Configure the matching secrets in `Settings → Secrets and variables → Actions`:
   - Cloudflare: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` + variable `CLOUDFLARE_PROJECT_NAME`
   - Vercel: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`
   - Netlify: `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID`
6. **Giscus** — update `repo`, `repoId`, `category`, `categoryId` in `GiscusComment.vue`
7. **PWA manifest** — edit `docs/.vitepress/vite-plugins/pwa.ts`

## Available Scripts

| Command | Description |
|---|---|
| `pnpm docs:dev` | Start dev server |
| `pnpm docs:build` | Build for production |
| `pnpm docs:preview` | Preview production build |

## Plugins

| Package | Purpose |
|---|---|
| [vitepress-plugin-mermaid](https://www.npmjs.com/package/vitepress-plugin-mermaid) | Mermaid diagram support |
| [vitepress-plugin-group-icons](https://www.npmjs.com/package/vitepress-plugin-group-icons) | Code group file-type icons |
| [vite-plugin-pwa](https://www.npmjs.com/package/vite-plugin-pwa) | PWA / service worker |
| [medium-zoom](https://www.npmjs.com/package/medium-zoom) | Image click-to-zoom |
| [sitemap](https://www.npmjs.com/package/sitemap) | Sitemap XML generation |
| [@giscus/vue](https://www.npmjs.com/package/@giscus/vue) | Giscus comment component |
| [@vitepress-plugin/markmap](https://www.npmjs.com/package/@vitepress-plugin/markmap) | Interactive mind maps from Markdown |
| [vitepress-plugin-tabs](https://www.npmjs.com/package/vitepress-plugin-tabs) | Tabbed content panels |
| [vitepress-demo-plugin](https://www.npmjs.com/package/vitepress-demo-plugin) | Live Vue/React/HTML demo preview |
| [vitepress-sidebar](https://www.npmjs.com/package/vitepress-sidebar) | Auto-generated sidebar |
| [vitepress-plugin-nprogress](https://www.npmjs.com/package/vitepress-plugin-nprogress) | Top loading progress bar |
| [vitepress-plugin-llms](https://www.npmjs.com/package/vitepress-plugin-llms) | Generate `llms.txt` for LLMs |
| [vitepress-plugin-rss](https://www.npmjs.com/package/vitepress-plugin-rss) | Generate `feed.rss` |

> Note: the mind-map plugin's npm name is **`@vitepress-plugin/markmap`** (there is no package named `vitepress-plugin-markmap`).
> See live examples at **Showcase → 新增插件示例** (`docs/showcase/new-plugins.md`).

## License

MIT

````

## 6. Frontmatter 页面配置

**语法说明**：每篇文档顶部 `---` 区域可配置页面元信息。常用字段：`title`（标题）、`description`（SEO 描述）、`layout`（`doc` 或 `home`）、`outline`（右侧大纲深度）、`aside`（是否显示右栏）、`prev`/`next`（自定义上下页）。

**示例写法**（当前页使用的）：

```yaml
---
title: VitePress 文档格式示例
description: 展示 VitePress 专属的扩展格式与可达到的排版效果
---
```

**实际效果**：上表字段已作用于本页——例如本页标题、右侧大纲、以及「上一篇 / 下一篇」导航均由 frontmatter 与配置驱动（可滚动到页面顶部与底部查看）。

首页布局（`layout: home`）示例见 `docs/index.md`：

```md
---
layout: home
hero:
  name: My Docs
  text: A VitePress Documentation Site
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
features:
  - title: Search
    details: Built-in full-text local search.
---
```

## 7. 静态资源引用

**语法说明**：放在 `docs/.vitepress/public/` 的资源以 `/` 开头引用（如 `/logo.svg`），构建时原样拷贝到产物根目录；其余图片建议与文档同目录用相对路径引用（如 `./logo.svg`）以避免构建报错。

**示例写法**：

```md
![Logo](/logo.svg)          <!-- public 目录资源 -->
![本地图片](./logo.svg)      <!-- 与文档同目录 -->
```

**实际效果**（public 目录资源，可点击放大）：

![Logo](./logo.svg)

## 8. 全站搜索

**语法说明**：搜索由 `themeConfig.search.provider: "local"` 提供内置全文检索，按 Ctrl+K（macOS 为 ⌘+K）唤起。

**示例写法**：

```md
按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 唤起搜索。
```

**实际效果**：

按 Ctrl + K 唤起搜索。

## 9. 导航与侧边栏

**语法说明**：导航栏与侧边栏在 `docs/.vitepress/config.ts` 的 `themeConfig.nav` / `themeConfig.sidebar` 中配置。本页所在的「Showcase」分组即通过以下配置新增：

**示例写法**：

```ts
nav: [
  { text: "Showcase", link: "/showcase/markdown" },
],
sidebar: {
  "/showcase/": [
    {
      text: "Showcase 示例",
      items: [
        { text: "Markdown 格式", link: "/showcase/markdown" },
        { text: "VitePress 格式", link: "/showcase/vitepress" },
        { text: "插件应用示例", link: "/showcase/plugins" },
      ],
    },
  ],
},
```

**实际效果**：上方配置已生效——顶部导航栏的「Showcase」与左侧本分组的三篇文档即由此生成。

---

---
url: /showcase/new-plugins.md
description: markmap 脑图、tabs 选项卡、demo 预览、nprogress、llms、rss、sidebar 的用法与效果
---

# 新增插件示例

本页演示新接入的 7 个插件。带  的可直接看到效果；带  的在 `docs:build` 时生效（生成文件或全局行为）。

| 插件 | 作用 | 类型 |
| --- | --- | --- |
| `@vitepress-plugin/markmap` | Markdown → 交互式脑图 | 实时渲染 |
| `vitepress-plugin-tabs` | 选项卡容器 | 实时渲染 |
| `vitepress-demo-plugin` | 代码 Demo 实时预览 | 实时渲染 |
| `vitepress-plugin-nprogress` | 路由切换顶部进度条 | 全局 |
| `vitepress-sidebar` | 自动生成侧边栏 | 全局 |
| `vitepress-plugin-llms` | 生成 `llms.txt` | 构建期 |
| `vitepress-plugin-rss` | 生成 `feed.rss` | 构建期 |

::: tip 关于包名
你最初要求的 `vitepress-plugin-markmap` 在 npm 上并不存在，真正的 markmap 插件包名是 **`@vitepress-plugin/markmap`**，本项目已按正确包名安装。
:::

## 1. markmap 脑图

**语法说明**：用 `:::markmap` 容器包裹一段标准 Markdown 大纲（`#` 标题 + 列表层级），即可渲染成可缩放、可折叠的交互式脑图。容器顶部可用 YAML frontmatter 覆盖高度、颜色、初始展开层级等。

**示例写法**：

```md
:::markmap
---
containerHeight: 420
markmap:
  initialExpandLevel: 2
---
# VitePress
## 特性
- 基于 Vite
- Vue 驱动
- Markdown 优先
## 插件
- Mermaid
- markmap
- tabs
## 部署
- GitHub Pages
- Cloudflare
- Vercel
:::
```

**实际效果**：

## 2. tabs 选项卡

**语法说明**：用 `:::tabs` 容器 + `== 标签名` 分隔多个面板，把并列内容（如不同包管理器、不同语言）折叠进选项卡，避免页面过长。

**示例写法**：

````md
::: tabs
== pnpm
```sh
pnpm add vitepress
```
== npm
```sh
npm i vitepress
```
:::
````

**实际效果**：

::: tabs
\== pnpm
安装命令：`pnpm add vitepress`
\== npm
安装命令：`npm i vitepress`
\== yarn
安装命令：`yarn add vitepress`
:::

## 3. demo 代码预览

**语法说明**：`vitepress-demo-plugin` 用 `<demo>` 组件把一个真实的 `.vue` / `.tsx` / `.html` 文件**同时**渲染为「实时效果 + 可展开源码」，非常适合组件库文档。

**示例写法**：

```md
<demo vue="./demos/hello.vue" title="计数器" />
```

**实际效果**：

## 4. nprogress 进度条&#x20;

**语法说明**：无需任何 Markdown 语法。在 `theme/index.ts` 的 `enhanceApp` 里调用一次，路由切换时页面顶部会出现加载进度条。

**示例写法**（`docs/.vitepress/theme/index.ts`）：

```ts
import vitepressNprogress from 'vitepress-plugin-nprogress'
import 'vitepress-plugin-nprogress/lib/css/index.css'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    vitepressNprogress(ctx)
  },
}
```

**实际效果**：点击左侧任意其它页面，观察浏览器视口**顶部**出现的细长进度条。

## 5. sidebar 自动侧边栏&#x20;

**语法说明**：`vitepress-sidebar` 用 `withSidebar()` 包裹配置，按目录结构自动生成侧边栏，标题优先取每个页面的 H1。你现在看到的**左侧菜单就是它自动生成的**——本页 `new-plugins` 也是自动出现的，无需手写。

**示例写法**（`docs/.vitepress/config.mts`）：

```ts
import { withSidebar } from 'vitepress-sidebar'

const sidebarOptions = ['guide', 'java', 'ai', 'showcase'].map((section) => ({
  documentRootPath: 'docs',
  scanStartPath: section,
  resolvePath: `/${section}/`,
  useTitleFromFileHeading: true,
  collapsed: false,
}))

export default withMermaid(withSidebar(vitePressOptions, sidebarOptions))
```

**实际效果**：左侧「Showcase 示例」分组下自动列出本目录所有页面。

## 6. llms 文档&#x20;

**语法说明**：`vitepress-plugin-llms` 在构建时生成符合 [llmstxt.org](https://llmstxt.org) 标准的 `llms.txt`（索引）与 `llms-full.txt`（全文合并），方便 AI/LLM 抓取你的文档。零配置即可用。

**示例写法**（`docs/.vitepress/config.mts`）：

```ts
import llmstxt from 'vitepress-plugin-llms'

export default defineConfig({
  vite: {
    plugins: [llmstxt()],
  },
})
```

**实际效果**：执行 `pnpm docs:build` 后，产物目录会生成 [`/llms.txt`](/llms.txt) 和 [`/llms-full.txt`](/llms-full.txt)（本地 `docs:dev` 下可能不可见，需构建后访问）。

## 7. rss 订阅&#x20;

**语法说明**：`vitepress-plugin-rss` 在构建时读取各页面 frontmatter（`title` / `date` / `description` / `author` / `category` / `cover`），生成 `feed.rss`，并自动在导航栏加上 RSS 图标。

**示例写法**（`docs/.vitepress/config.mts`）：

```ts
import { RssPlugin, type RSSOptions } from 'vitepress-plugin-rss'

const RSS: RSSOptions = {
  title: 'My Docs',
  baseUrl: 'https://example.com',
  copyright: 'Copyright © 2026 My Docs',
}

export default defineConfig({
  vite: { plugins: [RssPlugin(RSS)] },
})
```

页面 frontmatter 示例：

```md
---
title: 我的第一篇文章
date: 2026-01-15
description: 一篇关于 RSS 的介绍
author: chenzw
---
```

**实际效果**：`pnpm docs:build` 后生成 [`/feed.rss`](/feed.rss)。记得把配置里的 `baseUrl` 换成你的正式域名。

---

---
url: /404.md
---
# 404

## Page Not Found

The page you are looking for does not exist.

[Go back home](/)