Markdown语法速查

更新时间

最近更新：2023-7-31

搭建版本：vitepress v1.0.0-beta.5

如果你还不了解 Markdown ，请看别人整理的Markdown教程

说明

VitePress 相对于 VuePress 在Markdown中唯一的区别：链接可以直接渲染，不需要语法

基础功能

VitePress 使用 markdown-it 作为解析器，并使用 Shiki 来突出显示语言语法

基本配置

export default defineConfig({
  markdown:{
      //这里填配置项
  },
})

标题锚

标题会自动应用锚链接

说明

[] 中括号内文字随便输，() 括号里的填一个 # 号加标题

无论是几级标题，都是一个 # 号

输入：

[点我跳转：代码块](#代码块)

输出：

点我跳转：代码块

图片引用

这里涉及到一个相对路径 ./ 和 绝对路径 /

建议

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

链接

分为内部和外部链接，且默认情况下，生成链接带有 .html后缀

内部链接引用，输入：

[点我跳转：Frontmatter文章中的大纲](./frontmatter.md#大纲)

外部链接引用，输入：

* [vuejs.org](https://vuejs.org/)

* [GitHub 上的 VitePress](https://github.com/vuejs/vitepress)

输出：

• vuejs.org

• GitHub 上的 VitePress

表格

输入：

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

输出：

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

说明

更详细的使用方式，在 Markdown教程 里也说到过

也可使用 Execl 生成 Markdwon：https://tableconvert.com/zh-cn/

Emoji

输入：

:tada: :100:

输出：

🎉 💯

Emoji表情大全：https://emojixd.com/

目录

输入：

[[toc]]

输出：

点我查看当前页目录

• 基础功能
  • 标题锚
  • 图片引用
  • 链接
  • 表格
  • Emoji
  • 目录
• 容器
  • 基础使用
  • Badge组件
• 代码块
  • 语法突出
  • 行高亮
  • 聚焦代码
  • 增减差异
  • 错误和警告
  • 行号显示
  • 代码组
  • 导入代码
• 下载样式

容器

基础使用

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

输入：

::: info
这是一条信息，info后面的文字可修改
:::

::: tip 说明
这是一个提示，tip后面的文字可修改
:::

::: warning 警告
这是一条警告，warning后面的文字可修改
:::

::: danger 危险
这是一个危险警告，danger后面的文字可修改
:::

::: details 点我查看
这是一条详情，details后面的文字可修改
:::

输出：

INFO

这是一条信息，info后面的文字可修改

说明

这是一个提示，tip后面的文字可修改

警告

这是一条警告，warning后面的文字可修改

危险

这是一个危险警告，danger后面的文字可修改

点我查看

这是一条详情，details后面的文字可修改

我们在 details 中还可以加入代码块

点我查看

Hello, VitePress!

注意

官方有写关于 raw 使用，半吊子的我不是很明白使用场景

具体请看官方：https://vitepress.dev/guide/markdown#raw.html

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

您可以通过覆盖 css 变量来自定义徽章的 background-color

默认值：

点击查看css变量

:root {
  --vp-badge-info-border: var(--vp-c-divider-light);
  --vp-badge-info-text: var(--vp-c-text-2);
  --vp-badge-info-bg: var(--vp-c-white-soft);

  --vp-badge-tip-border: var(--vp-c-green-dimm-1);
  --vp-badge-tip-text: var(--vp-c-green-darker);
  --vp-badge-tip-bg: var(--vp-c-green-dimm-3);

  --vp-badge-warning-border: var(--vp-c-yellow-dimm-1);
  --vp-badge-warning-text: var(--vp-c-yellow-darker);
  --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3);

  --vp-badge-danger-border: var(--vp-c-red-dimm-1);
  --vp-badge-danger-text: var(--vp-c-red-darker);
  --vp-badge-danger-bg: var(--vp-c-red-dimm-3);
}

.dark {
  --vp-badge-info-border: var(--vp-c-divider-light);
  --vp-badge-info-bg: var(--vp-c-black-mute);

  --vp-badge-tip-border: var(--vp-c-green-dimm-2);
  --vp-badge-tip-text: var(--vp-c-green-light);

  --vp-badge-warning-border: var(--vp-c-yellow-dimm-2);
  --vp-badge-warning-text: var(--vp-c-yellow-light);

  --vp-badge-danger-border: var(--vp-c-red-dimm-2);
  --vp-badge-danger-text: var(--vp-c-red-light);
}

代码块

代码块基本用法，就是上下三个反引号

输入：

```md(常用的还有 `ts` `js` `yaml` `sh` 等等，但这里尽量不要出现中文)
中间写代码内容
```

语法突出

VitePress有着 Shiki 插件的加持

我们在前反引号后可以写入代码的语法，渲染后会显示在代码块右上方

输入：

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

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

输出：

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

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

行高亮

比如我要第4行显示

输入：

```ts{4}
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 focus] 注释会聚焦该行，并模糊代码的其他部分

输入：

说明

!code 后面只需要一个空格，这里有两个空格是为了防止处理

```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>]

说明

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

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

输入：

说明

!code 后面只需要一个空格，这里有两个空格是为了防止处理

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

输出：

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

增减差异

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

输入：

说明

!code 后面只需要一个空格，这里有两个空格是为了防止处理

```ts{3-4}
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] 注释会相应地为其着色

输入：

说明

!code 后面只需要一个空格，这里有两个空格是为了防止处理

```ts{3-4}
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,
  },
})

如果你在某个代码块不想使用，可以通过 ts:no-line-numbers 来临时关闭

输入：

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

输出：

无行号演示

代码组

和Vuepress不同，我们用 code-group 包裹

::: code-group
:::

输入：

::: code-group

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

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

:::

输出：

pnpm

#查询pnpm版本
pnpm -v

yarn

#查询yarn版本
yarn -v

导入代码

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

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

注意

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

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

原文件修改示例：

// #region fav //
  head: [
    ['link',{ rel: 'icon', href: 'https://vitejs.cn/vite3-cn/logo-with-shadow.png'}],
  ],
  // #endregion fav //

下载样式

<a class="jump-link" href="你的链接" target="_blank">点击跳转</a>
<a class="download-button" href="下载链接"\">点击下载</a>

点击跳转

点击下载