VitePress 主题配置与 Markdown 语法指南
一、VitePress Theme 配置参数
以下是 VitePress 主题配置的常用参数说明：
1. 基础配置
typescript
import { defineConfig } from 'vitepress'
export default defineConfig({
title: "Cloink-产品文档",
description: "A starter template for VitePress",
themeConfig: {
// Logo 配置
logo: '/images/logo.png',
// 站点标题
siteTitle: 'Cloink',
// 导航栏配置
nav: [
{ text: '首页', link: '/' },
{ text: '产品介绍', link: '/introduce/introduce.md' },
{ text: '快速开始', link: '/quick-start/quick-start.md' },
// 下拉菜单
{
text: '更多',
items: [
{ text: 'Markdown 示例', link: '/examples/markdown-examples' },
{ text: 'API 示例', link: '/examples/api-examples' }
]
}
],
}
})2. 侧边栏配置
typescript
sidebar: {
'/': [
{
text: '产品介绍',
collapsed: true,
items: [
{ text: '产品介绍', link: '/introduce/introduce.md' },
{ text: '快速开始', link: '/quick-start/quick-start.md' }
]
},
{
text: '使用案例',
items: [
{ text: 'Markdown Examples', link: '/examples/markdown-examples' },
{ text: 'API Examples', link: '/examples/api-examples' }
]
}
]
}3. 社交链接与页脚
typescript
socialLinks: [
{ icon: 'github', link: 'https://github.com/your-repo' },
{ icon: 'twitter', link: 'https://twitter.com/your-twitter' },
{ icon: 'linkedin', link: 'https://linkedin.com/company/your-company' }
],
footer: {
message: 'Released under the MIT License.',
copyright: '2024 Cloink. All rights reserved.'
}4. 大纲与搜索
typescript
outline: {
level: [1, 3], // 显示 h1 到 h3 级标题
label: '页面目录'
},
lastUpdated: true, // 显示最后更新时间
search: {
provider: 'local',
options: {
locales: {
root: {
translations: {
button: {
buttonText: '搜索',
buttonAriaLabel: '搜索文档'
}
}
}
}
}
}二、Markdown 语法示例
1. 标题
markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题2. 文本样式
| 样式 | 语法 | 效果 |
|---|---|---|
| 加粗 | **文本** | 加粗文本 |
| 斜体 | *文本* | 斜体文本 |
| 删除线 | ~~文本~~ | |
| 行内代码 | `代码` | const a = 1 |
3. 代码块
支持多种语言语法高亮：
js
// JavaScript
function greet(name) {
console.log(`Hello, ${name}!`);
}
greet('World');python
# Python
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
print(fibonacci(10))typescript
// TypeScript
interface User {
id: number;
name: string;
email: string;
}
const user: User = {
id: 1,
name: 'John',
email: 'john@example.com'
};4. 列表
无序列表
markdown
- 项目一
- 项目二
- 嵌套项目 A
- 嵌套项目 B
- 项目三有序列表
markdown
1. 第一步
2. 第二步
3. 第三步
1. 子步骤 3.1
2. 子步骤 3.2
4. 第四步5. 链接与图片
markdown
[外部链接](https://vitepress.dev)
[内部链接](/introduce/introduce.md)
[带标题的链接](https://vitepress.dev "VitePress 官网")
6. 表格
markdown
| 功能模块 | 描述 | 状态 |
|----------|------|------|
| 远程办公接入 | 无感安全接入体验 | ✅ 已完成 |
| 多分支互联 | 混合模式支持 | ✅ 已完成 |
| NAT穿透 | 高效网络穿透 | ⚡ 进行中 |
| DNS管理 | 集中管理DNS配置 | 📋 待开发 |7. 自定义容器
VitePress 提供了三种预设容器：
markdown
:::tip
这是提示信息容器，用于展示有用的提示内容。
:::
:::warning
这是警告信息容器，用于展示需要注意的内容。
:::
:::danger
这是危险信息容器，用于展示重要的警告或错误信息。
:::效果：
TIP
这是提示信息容器，用于展示有用的提示内容。
WARNING
这是警告信息容器，用于展示需要注意的内容。
DANGER
这是危险信息容器，用于展示重要的警告或错误信息。
8. 引用
markdown
> 这是一段引用文字。
>
> 引用可以包含多个段落，每行开头都需要 `>` 符号。
>
> —— 作者名称9. 任务列表
markdown
- [x] 完成项目初始化
- [x] 添加主题配置
- [ ] 编写文档内容
- [ ] 测试构建10. 数学公式
需要启用 math 插件支持：
markdown
E = mc^2
$$
\int_{a}^{b} f(x) \, dx = F(b) - F(a)
$$三、Hero 区域配置
首页 Hero 区域支持丰富的配置选项：
yaml
hero:
name: "Cloink"
text: "安全组网工具"
tagline: 安全组网 多分支互联
image:
src: /images/logo.png
alt: Cloink Logo
width: 200
height: 200
actions:
- theme: brand
text: 快速开始
link: /quick-start/quick-start.md
- theme: alt
text: 了解更多
link: /introduce/introduce.mdAction Button 主题
| 主题 | 样式 | 用途 |
|---|---|---|
brand | 蓝色背景 | 主要操作按钮 |
alt | 灰色背景 | 次要操作按钮 |
四、Features 区域配置
yaml
features:
- title: <i class="fa-regular fa-building"></i> 远程办公接入
details: 无感安全接入体验，弱网环境下性能优化，精细化权限管控。
- title: <i class="fa-solid fa-globe"></i> 多分支网络安全接入
details: 支持无客户端及安装客户端混合模式，集中管理DNS配置。
- title: <i class="fa-solid fa-bolt-lightning"></i> 高效NAT穿透
details: 配置和管理维护简单，实现任意设备之间高效NAT穿透。五、配置文件结构
.vitepress/
├── config.mts # 主配置文件
└── theme/
├── index.ts # 自定义主题入口
└── style.css # 自定义样式六、徽章
Title default
Title ^1.9.0
Title beta
Title caution
### Title <Badge type="info" text="default" />
### Title <Badge type="tip" text="^1.9.0" />
### Title <Badge type="warning" text="beta" />
### Title <Badge type="danger" text="caution" />更多详细配置请参考 VitePress 官方文档。