CreateHub

主题

Markdown 功能 ​

VitePress 在标准 Markdown 之上加了很多功能，专为技术文档优化。

基础配置 ​

ts
markdown: {
  breaks: true,         // 允许单行换行
  math: true,           // LaTeX 数学公式
  lineNumbers: true,    // 代码块全局显示行号
  image: {
    lazyLoading: true,  // 图片懒加载
  },
}

标题锚点 ​

所有标题自动生成锚点，鼠标悬停标题会显示 # 链接图标。

自定义锚点 ​

md
# 我的标题 {#my-custom-id}

链接就可以用 #my-custom-id 而不是 #我的标题。

链接 ​

内部链接 ​

内部链接自动转为路由链接，省略 .md 或 .html 是最佳实践：

md
[推荐] [快速开始](./快速开始)
[可以但不推荐] [快速开始](./快速开始)

index.md 会映射到 /，所以：

md
[教程首页](/VitePress 配置教程/)  ← 实际访问 /VitePress 配置教程/index.html

外部链接 ​

自动加 target="_blank" rel="noreferrer"，点开会开新标签页。

语法高亮 ​

VitePress 用 Shiki 提供语法高亮，支持所有主流语言。

行高亮 ​

在代码块的语言后加 {行号}：

md
```js{4}         ← 高亮第 4 行
export default {
  data () {
    return {
      msg: '高亮这行!'
    }
  }
}
```

多行组合：

{1,4,6-8}   → 第1行、第4行、第6到第8行
{5-8}       → 第5到第8行
{4,7,9}     → 第4、7、9行

行号 ​

全局开启：

ts
markdown: {
  lineNumbers: true,
}

单个代码块控制：

md
```ts:line-numbers       ← 强制开启行号
const a = 1
```

```ts:no-line-numbers    ← 强制关闭行号
const a = 1
```

```ts:line-numbers=2     ← 开启行号，从 2 开始
const a = 1
```

代码注释标记 ​

在代码中用特殊注释实现更多效果：

md
```js
export default {
  data () {
    return {
      msg: '高亮!'       //  ← 行高亮
      msg: '聚焦!'       //       ← 聚焦当前行
      msg: '删除了'      //          ← 删除标记（红色）
      msg: '新增的'      //          ← 新增标记（绿色）
      msg: '错误!'       //       ← 错误标记
      msg: '警告'        //     ← 警告标记
    }
  }
}
```

代码组 ​

把多个代码块组合在一起，用标签页切换：

md
::: code-group

```js [config.js]
export default {
  // JavaScript 配置
}
```

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

const config: UserConfig = {
  // TypeScript 配置
}
```

:::

导入外部代码 ​

直接从文件导入代码片段，不需要复制粘贴：

md
<<< @/snippets/example.js
<<< @/snippets/example.js{2}           ← 高亮第2行
<<< @/snippets/example.js#region{1}   ← 导入指定 region

@ 代表源目录根目录。

自定义容器 ​

五种内置容器：

md
::: info
这是一个信息框。
:::

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

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

::: danger
这是一个危险警告。
:::

::: details
这是一个折叠块，点击展开查看。
:::

自定义标题 ​

md
::: danger STOP
危险区域，请勿继续
:::

::: details 点我看代码
console.log('Hello!')
:::

全局设置容器标题 ​

如果需要中文标题，在配置中设置：

ts
markdown: {
  container: {
    tipLabel: '提示',
    warningLabel: '警告',
    dangerLabel: '危险',
    infoLabel: '信息',
    detailsLabel: '详细信息',
  },
}

GitHub 风格警报 ​

md
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。

> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。

> [!IMPORTANT]
> 对用户达成目标至关重要的信息。

> [!WARNING]
> 因为可能存在风险，需要用户立即关注的关键内容。

目录（TOC） ​

md
[[toc]]

在任意位置插入页面目录。

Emoji ​

:smile: :+1: :tada: :rocket: :100:

完整 Emoji 列表

数学公式 ​

先开启 markdown.math: true，然后用 LaTeX 语法：

md
行内公式：$E = mc^2$

块级公式：
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

包含 Markdown 文件 ​

在一个文件中嵌入另一个文件的内容：

md
<!--@​include: ./parts/basics.md-->
<!--@​include: ./parts/basics.md{3,}-->
<!--@​include: ./parts/basics.md{,10}-->
<!--@​include: ./parts/basics.md{1,10}-->

表格 ​

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |

左边冒号左对齐，两边冒号居中对齐，右边冒号右对齐。

Frontmatter ​

每个 .md 文件顶部可以用 YAML 设置页面级配置：

yaml
---
title: 页面标题
description: 页面描述（SEO）
outline: deep           # 右侧目录深度
head:                   # 这个页面单独注入 <head>
  - - meta
    - name: robots
    - content: noindex
---

更多 frontmatter 选项见官方 Frontmatter 配置参考。

扩展 Markdown 插件 ​

VitePress 兼容所有 markdown-it 插件：

ts
markdown: {
  async config(md) {
    // 动态导入避免 SSR 问题
    const plugin = (await import('插件名')).default
    md.use(plugin, { /* 选项 */ })
  }
}

本站用的自定义插件就是这个方式加载的：[[维基链接]]、==高亮文本==、![[图片]]。

Powered by VitePress