Markdown 基础功能

标题

以 # 号开头，后面至少一个空格，和 H1~H6 一样的

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

##### 五级标题

###### 六级标题

列表

无序列表

以 - 开头，后面至少一个空格，标识为实心 ● 圆点

输入：

- 第一个项目
- 第二个项目
- 第三个项目

输出：

第一个项目
第二个项目
第三个项目

有序列表

以 1. 开头，后面至少一个空格，标识为数字序号

输入：

1. 第一个项目
2. 第二个项目
3. 第三个项目

输出：

第一个项目
第二个项目
第三个项目

层级列表

和无序列表一样，使用 * 号开头

每下一层比上一层多 2 个空格

注意

第一层前面不可超过 3 个空格

第一级的标识为实心 ● 圆点，第二级的标识为空心 ○ 圆点，第 3 级以后的标识均为实心 ■ 方点

输入：

- 第一层
  - 第二层
    - 第三层
      - 第四层
        - 第五层

输出：

第一层
- 第二层
  - 第三层
    - 第四层
      - 第五层

引用

以 > 号开头，后面至少一个空格，标识为引用

输入：

> 青玉案·元夕
>
> > 辛弃疾
> >
> > > 东风夜放花千树。更吹落、星如雨。宝马雕车香满路。凤箫声动，玉壶光转，一夜鱼龙舞。
> > > 蛾儿雪柳黄金缕。笑语盈盈暗香去。众里寻他千百度。蓦然回首，那人却在，灯火阑珊处。

输出：

青玉案·元夕
辛弃疾
东风夜放花千树。更吹落、星如雨。宝马雕车香满路。凤箫声动，玉壶光转，一夜鱼龙舞。蛾儿雪柳黄金缕。笑语盈盈暗香去。众里寻他千百度。蓦然回首，那人却在，灯火阑珊处。

字体

以 _ 号开头，后面至少一个空格，标识为斜体
以 ** 号开头，后面至少一个空格，标识为粗体
以 **_ 号开头，后面至少一个空格，标识为粗斜体

输入：

_斜体_
**粗体**
**_粗斜体_**
<del>删除线</del>
`高亮`
<u>下划线</u>

<span style="border-bottom:2px dashed yellow;">加下划线用的是 html 代码</span>

输出：

斜体

粗体

粗斜体

~~删除线~~

高亮

下划线

加下划线用的是 html 代码

图片

![替代文字](图片地址)

注意

[ ]中括号的替代文字可留空

内部图片

提示

对于指向内部 Markdown 文件的链接，尽可能使用相对路径，而不是绝对路径

由于 public 文件夹的特殊性，可以直接使用 ![LOGO](/logo.png) 即可

输入：

<!-- 相对路径，目标文件相对于本文章所在位置 -->

![LOGO](./public/logo.png)

<!-- 绝对路径，目标文件就是真实路径在哪 -->

![LOGO](/public/logo.png)

<!-- public文件夹直接使用 -->

![LOGO](/logo.png)

输出：

外部图片

输入：

![趣格子logo](https://wiki.fungrids.com/logo.png)

输出：

地址失效情况:

趣格子logo

视频

本地视频

视频用 HTML5 自带的 <video> 即可

输入：

<video src="/本地视频路径.mp4" controls="controls"></video>

在线视频

可以用 <iframe> 标签实现

输入：

<iframe
style="width:100%; aspect-ratio:16/9; margin-top: 2em;"
src="//player.bilibili.com/player.html?bvid=BV1xm421p7Ey&autoplay=0"
frameborder="0"
allowfullscreen>
</iframe>

链接

格式 1：[这里填文字](这里是跳转的网址)

格式 2：[这里填文字](这里是跳转的网址 "这里填鼠标放上去显示的文字")

内部链接

输入：

[点我跳转：CSS 技巧文章中的网页置灰](../../frontend/css/tricks.md#网页置灰)

输出：

点我跳转：CSS 技巧文章中的网页置灰

外部链接

输入：

[趣格子](https://www.fungrids.com)

[趣格子](https://www.fungrids.com "趣格子")

输出：

趣格子

自动链接

格式：<这里填网址>

输入：

<https://www.fungrids.com>

输出：

https://www.fungrids.com

分割线

以 --- 开头，后面至少一个空格，标识为分割线

输入：

---

输出：

代码块

Prism.js 官方语言列表

单行代码

2 个反引号，中间写文字或者代码

输入：

`单行代码`

输出：

单行代码

多行代码

上下三个反引号 ``` 开始和结尾，中间放内容/文字/代码

输入：

```sh
npm run docs:dev
```

输出：

npm run docs:dev

代码块嵌套

比如想展示代码块的写法，但是反引号已经用了，那么我们就用 4 个反引号 ```` ，以此类推即可

输入：

````sh
```sh
npm run docs:dev
```
````

输出：

```sh
npm run docs:dev
```

代码新增行加亮

加入 diff 即可，+ 或 - 都可以表示

输入：

```diff
- npm run docs:dev
+ npm run dev
```

输出：

diff

- npm run docs:dev
+ npm run dev

行高亮

比如我要第 2-3 行和第 5 行显示，连续行用 - ，不连续行用 ,

单行：例如 {5}
多行：例如 {5-8}、{3-10}、{10-17}
多个单行：例如 {4,7,9}
多行与单行：例如 {4,7-13,16,23-27,40}

输入：

```ts{2-3,5}
export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程",
  titleTemplate: '另起标题覆盖title' ,
})
```

输出：

export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程",
  titleTemplate: '另起标题覆盖title' ,
})

也可以使用 // [!code highlight]

输入：

```ts
export default defineConfig({
  lang: "zh-CN",
  title: "VitePress",
  description: "我的vitpress文档教程", // [!code highlight]
});
```

输出：

export default defineConfig({
  lang: "zh-CN",
  title: "VitePress",
  description: "我的vitpress文档教程", 
});

也可以通过 // [!code highlight:<lines>] 连续行号

输入：

```ts
export default defineConfig({
  lang: "zh-CN", // [!code highlight:3]
  title: "VitePress",
  description: "我的vitpress文档教程",
});
```

输出：

export default defineConfig({
  lang: "zh-CN", 
  title: "VitePress",
  description: "我的vitpress文档教程",
});

聚焦代码

在某一行后添加 // [!code focus] 注释会聚焦该行，并模糊代码的其他部分

输入：

```ts{4}
export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", // [!code focus]
  titleTemplate: '另起标题覆盖title' ,
})
```

输出：

export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", 
  titleTemplate: '另起标题覆盖title' ,
})

如果你要聚焦连续多行，可以使用 // [!code focus:<lines>]

说明

从添加行的位置开始，输入最终聚焦的行号即可

分散的行，请单独添加使用

输入：

```ts{2-5}
export default defineConfig({
  lang: 'zh-CN', // [!code focus:4]
  title: "VitePress",
  description: "我的vitpress文档教程",
  titleTemplate: '另起标题覆盖title' ,
})
```

输出：

export default defineConfig({
  lang: 'zh-CN', 
  title: "VitePress",
  description: "我的vitpress文档教程",
  titleTemplate: '另起标题覆盖title' ,
})

增减差异

在某一行上添加 // [!code --] 或 // [!code ++] 注释将创建该行的差异，同时保留代码块的颜色

输入：

```ts{4-5}
export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", // [!code --]
  description: "更详细的vitpress中文文档教程", // [!code ++]
  titleTemplate: '另起标题覆盖title' ,
})
```

输出：

export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", 
  description: "更详细的vitpress中文文档教程", 
  titleTemplate: '另起标题覆盖title' ,
})

错误和警告

在某一行上添加 // [!code warning] 或 // [!code error] 注释会相应地为其着色

输入：

```ts{4-5}
export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", // [!code error]
  description: "更详细的vitpress中文文档教程", // [!code warning]
  titleTemplate: '另起标题覆盖title' ,
})
```

输出：

export default defineConfig({
  lang: 'zh-CN',
  title: "VitePress",
  description: "我的vitpress文档教程", 
  description: "更详细的vitpress中文文档教程", 
  titleTemplate: '另起标题覆盖title' ,
})

行号显示

export default defineConfig({
  //markdown配置
  markdown: {
    //行号显示
    lineNumbers: true, //false关闭
  },
})

可以在代码块中添加 :line-numbers / :no-line-numbers 标记来覆盖在配置中的设置。

还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，例如 :line-numbers=2 表示代码块中的行号从 2 开始。

输入：

```ts:no-line-numbers
// 无行号演示
```

```ts:line-numbers=2 {1}
// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

输出：

// 无行号演示

// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'

代码组

用 code-group 包裹

::: code-group
:::

输入：

::: code-group

```sh [pnpm]
#查询pnpm版本
pnpm -v
```

```sh [yarn]
#查询yarn版本
yarn -v

```

:::

输出：

pnpmyarn

#查询pnpm版本
pnpm -v

#查询yarn版本
yarn -v

config.jsconfig.ts

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
};

export default config;

import type { UserConfig } from "vitepress";

const config: UserConfig = {
  // ...
};

export default config;

已经内置的常用代码组图标有

export const builtinIcons = {
  // package managers
  pnpm: "vscode-icons:file-type-light-pnpm",
  npm: "vscode-icons:file-type-npm",
  yarn: "vscode-icons:file-type-yarn",
  bun: "vscode-icons:file-type-bun",
  deno: "vscode-icons:file-type-deno",
  // frameworks
  vue: "vscode-icons:file-type-vue",
  svelte: "vscode-icons:file-type-svelte",
  angular: "vscode-icons:file-type-angular",
  react: "vscode-icons:file-type-reactjs",
  next: "vscode-icons:file-type-light-next",
  nuxt: "vscode-icons:file-type-nuxt",
  solid: "logos:solidjs-icon",
  astro: "vscode-icons:file-type-light-astro",
  // bundlers
  rollup: "vscode-icons:file-type-rollup",
  webpack: "vscode-icons:file-type-webpack",
  vite: "vscode-icons:file-type-vite",
  esbuild: "vscode-icons:file-type-esbuild",
  // configuration files
  "package.json": "vscode-icons:file-type-node",
  "tsconfig.json": "vscode-icons:file-type-tsconfig",
  ".npmrc": "vscode-icons:file-type-npm",
  ".editorconfig": "vscode-icons:file-type-editorconfig",
  ".eslintrc": "vscode-icons:file-type-eslint",
  ".eslintignore": "vscode-icons:file-type-eslint",
  "eslint.config": "vscode-icons:file-type-eslint",
  ".gitignore": "vscode-icons:file-type-git",
  ".gitattributes": "vscode-icons:file-type-git",
  ".env": "vscode-icons:file-type-dotenv",
  ".env.example": "vscode-icons:file-type-dotenv",
  ".vscode": "vscode-icons:file-type-vscode",
  "tailwind.config": "vscode-icons:file-type-tailwind",
  "uno.config": "vscode-icons:file-type-unocss",
  "unocss.config": "vscode-icons:file-type-unocss",
  ".oxlintrc": "vscode-icons:file-type-oxlint",
  // filename extensions
  ".mts": "vscode-icons:file-type-typescript",
  ".cts": "vscode-icons:file-type-typescript",
  ".ts": "vscode-icons:file-type-typescript",
  ".tsx": "vscode-icons:file-type-typescript",
  ".mjs": "vscode-icons:file-type-js",
  ".cjs": "vscode-icons:file-type-js",
  ".json": "vscode-icons:file-type-json",
  ".js": "vscode-icons:file-type-js",
  ".jsx": "vscode-icons:file-type-js",
  ".md": "vscode-icons:file-type-markdown",
  ".py": "vscode-icons:file-type-python",
  ".ico": "vscode-icons:file-type-favicon",
  ".html": "vscode-icons:file-type-html",
  ".css": "vscode-icons:file-type-css",
  ".scss": "vscode-icons:file-type-scss",
  ".yml": "vscode-icons:file-type-light-yaml",
  ".yaml": "vscode-icons:file-type-light-yaml",
  ".php": "vscode-icons:file-type-php",
};

代码组中添加图片

有的时候，我们需要在代码组中添加图片，来展示代码的运行结果

输入：

::: code-group

```shell [pnpm]
npm i pnpm -g
```

```md:img [cmd 控制台]
![](/logo.png)
```

:::

输出：

pnpmcmd 控制台

shell

npm i pnpm -g

导入代码

可以通过下面的语法来从现有文件中导入代码片段,同时支持行高亮：

<<< @/filepath
<<< @/filepath{highlightLines}

输入：

<<< @/vite.config.ts{2}

import { defineConfig } from 'vite'
import path from 'path'
import {
  groupIconVitePlugin,
  localIconLoader,
} from 'vitepress-plugin-group-icons'
import { MermaidPlugin } from 'vitepress-plugin-mermaid'
import { demoblockVitePlugin } from 'vitepress-theme-demoblock'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    groupIconVitePlugin({
      customIcon: {
        ts: localIconLoader(import.meta.url, './public/svg/typescript.svg'), //本地ts图标导入
        css: localIconLoader(import.meta.url, './public/svg/css.svg'), //css图标
        js: 'logos:javascript', //js图标
        md: 'vscode-icons:file-type-markdown',
      },
    }),
    MermaidPlugin(),
    demoblockVitePlugin(),
    AutoImport({ imports: ['vue', 'vue-router'] }),
  ],
  optimizeDeps: {
    include: ['mermaid'],
  },
  ssr: {
    noExternal: ['mermaid'],
  },
  server: {
    port: 5001,
  },
  resolve: {
    // 路径别名
    alias: {
      '@': path.resolve(__dirname, './'),
    },
    // 导入时想要省略的扩展名集合
    extensions: [
      '.js',
      '.ts',
      '.jsx',
      '.tsx',
      '.json',
      '.mjs',
      '.mts',
      '.cjs',
      '.cts',
    ],
  },
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use "sass:math";`,
      },
    },
  },
})

要输出准确的文件路径，可以指定代码的片段和高亮部分

导入片段，我们需要对原文件进行注释 // #region 和 // #endregion

注意

开始和结束都要有，后面的字必须是字母，不能汉字!

可以自定义，比如示例中的 fav

原文件修改示例：

  // #region fav
  head: [
    ['link',{ rel: 'icon', href: '/logo.png'}],
  ],
  // #endregion fav

输入：

说明

{} 大括号中是高亮的行号

<!-- 绝对路径 二选一-->

<<< @/.vitepress/config.mts#fav{2}

<!-- 相对路径 二选一-->

<<< ./.vitepress/config.mts#fav{2}

锚点

格式：[说明文字](#要跳转的位置)

注意

注意:无论是几级标题，都只用一个#

输入：

[跳转到代码块的位置](#代码块)

输出：

跳转到代码块的位置

表格

第一行：表头行，用 | 隔开，控制分列
第二行：控制行，用 - 隔开，控制分行

提示

使用冒号 : 可控制对齐方式
:- 表示左对齐
.或 :-: 表示中对齐
: 表示右对齐

第三行及以下：数据行,用 | 隔开

输入：

| 名字 | 性别 | 年龄 | 部门 |
| :--: | :--: | :--: | :--: |
| 张三 |  男  |  21  | 产品 |
| 李四 |  女  |  18  | 开发 |
| 王二 |  男  |  20  | 销售 |

输出：

名字	性别	年龄	部门
张三	男	21	产品
李四	女	18	开发
王二	男	20	销售

提示

采用 html 的<table>标签也可以实现

align="center" ：居中
colspan="2" ：横向合并 2 格
rowspan="2" ：纵向合并 2 格

觉得麻烦，可以用在线表格转换工具

输入：

<table>
    <tbody>
        <tr>
            <td align="center">名字</td>
            <td align="center">性别</td>
            <td align="center">年龄</td>
            <td align="center">部门</td>
        </tr>
        <tr>
            <td align="center">张三</td>
            <td align="center">男</td>
            <td align="center">21</td>
            <td align="center" rowspan="2">产品</td>
        </tr>
        <tr>
            <td align="center">李四</td>
            <td align="center">女</td>
            <td align="center">18</td>
        </tr>
        <tr>
            <td align="center" colspan="2">王二 男</td>
            <td align="center">20</td>
            <td align="center">销售</td>
        </tr>
    </tbody>
</table>

输出：

名字	性别	年龄	部门
张三	男	21	产品
李四	女	18	产品
王二男		20	销售

Emoji

输入：

:100: :joy: :grapes:

输出：

💯 😂 🍇

Emoji 大全

目录表

输入：

[[toc]]

输出：

点我查看当前页目录

[[toc]]

折叠语法

输入：

::: details 点我展开
Markdown 默认折叠语法，Vitepress 可以使用容器折叠语法，更加美观
:::

<details>
  <summary>点我展开</summary>
  Markdown默认折叠语法，Vitepress可以使用容器折叠语法，更加美观
</details>

输出：

点我展开

Markdown 默认折叠语法，Vitepress 可以使用容器折叠语法，更加美观

点我展开

Markdown默认折叠语法，Vitepress可以使用容器折叠语法，更加美观

容器

容器可以通过其类型、标题和内容来定义

输入：

::: info
这是一条 info，自定义格式：info+空格+自定义文字
:::

::: tip 提示
这是一个提示，自定义格式：tip+空格+自定义文字
:::

::: warning 警告
这是一条警告，自定义格式：warning+空格+自定义文字
:::

::: danger 危险
这是一个危险警告，自定义格式：danger+空格+自定义文字
:::

::: details 点我查看
这是一条详情，自定义格式：details+空格+自定义文字
:::

INFO

这是一条 info，自定义格式：info+空格+自定义文字

提示

这是一个提示，自定义格式：tip+空格+自定义文字

警告

这是一条警告，自定义格式：warning+空格+自定义文字

危险

这是一个危险警告，自定义格式：danger+空格+自定义文字

点我查看

这是一条详情，自定义格式：details+空格+自定义文字

Badge 组件

徽章可让您向标题添加状态

输入：

- VitePress <Badge type="info" text="default" />
- VitePress <Badge type="tip" text="^1.9.0" />
- VitePress <Badge type="warning" text="beta" />
- VitePress <Badge type="danger" text="caution" />

输出：

VitePress default
VitePress ^1.9.0
VitePress beta
VitePress caution

你也可以自定义 children

输入：

- VitePress <Badge type="info">custom element</Badge>

输出：

VitePress custom element

Markdown 基础功能 ​

标题 ​

列表 ​

无序列表 ​

有序列表 ​

层级列表 ​

引用 ​

字体 ​

图片 ​

内部图片 ​

外部图片 ​

视频 ​

本地视频 ​

在线视频 ​

链接 ​

内部链接 ​

外部链接 ​

自动链接 ​

分割线 ​

代码块 ​

单行代码 ​

多行代码 ​

代码块嵌套 ​

代码新增行加亮 ​

行高亮 ​

聚焦代码 ​

增减差异 ​

错误和警告 ​

行号显示 ​

代码组 ​

代码组中添加图片 ​

导入代码 ​

锚点 ​

表格 ​

Emoji ​

目录表 ​

折叠语法 ​

容器 ​

Badge 组件 ​