vitepress组件库文档项目 markdown语法大全(修正版)

#上次总结的 有些语法是用在markdown文档中的 使用到vitepress项目中有些语法可能有出入 于是我再总结一版  vitepress项目中的markdown语法大全

在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些Markdown 教程#

VitePress组件库文档项目中的Markdown语法十分丰富，它允许在Markdown文档中嵌入Vue语法，使得文档更加动态和交互。以下是一个关于VitePress中Markdown语法的大全，结合了Vue语法的使用

 一、基础Markdown语法

• 标题：使用#号表示不同级别的标题，如# 一级标题、## 二级标题等。

# 一级标题
## 二级标题
### 三级标题

• 列表：使用-或*表示无序列表，使用数字加.表示有序列表。

 

#无序列表
- 列表项一
- 列表项二
- 列表项三#有序列表
1. 列表项一
2. 列表项二
3. 列表项三

• 链接：使用[文本](链接)表示超链接。

[这是一个链接](https://www.baidu.com) 

• 图片：使用![描述](图片链接)表示图片。

![这是一张图片](https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg)

• 代码块：使用三个反引号```包围代码，并可以指定语言进行高亮显示，如```javascript```。

```javascript
// 这是一个代码块
console.log('Hello, Vitepress!');```

• 表格：使用| 表头1 | 表头2 | 表头3 |表示表格。

| 表头1 | 表头2 | 表头3 |
|-------|-------|-------|
| 单元格1 | 单元格2 | 单元格3 |
| 单元格4 | 单元格5 | 单元格6 |

• 加粗和斜体。

**这是加粗文本**
*这是斜体文本*

• 分割线。

---

• 引用。

> 这是一个引用。

二、Markdown在vitepress使用扩展

• 内部链接。

内部链接将会转化成路由链接用于SPA导航。同时，每一个文件夹下的 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /。

以下列目录结构为例：

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar├─ index.md├─ three.md└─ four.md

 假设你在foo/one.md中：

[Home](/) <!-- 跳转到根目录的index.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html-->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three) <!-- 你可以忽略扩展名 -->
[bar - three](../bar/three.md) <!-- 具体文件可以使用 .md 结尾（推荐）-->
[bar - four](../bar/four.html) <!-- 也可以用 .html-->

页面后缀

页面和内部链接默认生成.html后缀。

• 外部链接

出站链接自动添加target="_blank" rel="noopener noreferrer"。 

• 表情符号

输入：

:tada: :100:

输出： 

🎉 💯

A list of all emojis is available.

• 自定义容器

自定义容器可通过他们的类型、标题和内容来定义。

输入： 

::: tip
This is a tip
:::::: warning
This is a warning
:::::: danger
This is a dangerous warning
:::

输出： 

 

• 自定义标题

输入： 

::: danger STOP
Danger zone, do not proceed
:::

输出： 

• 在语法块中的语法高亮

VitePress 通过 Prism来实现Markdown中语法块的语法高亮，使用了有色文本。 Prism 支持大量的编程语言，你需要做的只是在代码块的开始反引号后附加一个有效的语言别名

输入： 

```js
export default {name: 'MyComponent',// ...
}
```

 输出：

输入：

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

输出： 

• 代码块中的行高亮

输入：

```js{4}
export default {data () {return {msg: 'Highlighted!'}}
}
```

输出： 

除了指定单号以外，你也可以指定多个单行、区间或两者皆有：

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

输入：

```js{1,4,6-7}
export default { // Highlighteddata () {return {msg: `Highlighted!This line isn't highlighted,but this and the next 2 are.`,motd: 'VitePress is awesome',lorem: 'ipsum',}}
}
```

 输出：

• 行号

你可以通过全局配置 config中增加启用行号

module.exports = {markdown: {lineNumbers: true}
}

 局部标记(推荐使用)

语法 ：

1.  直接在代码块类型的后面添加 :line-numbers 即表示开启行号

2. 直接在代码块类型的后面添加 :no-line-numbers 即表示关闭行号展示

# 代码块-配置启用行号
```java:line-numberspublic class HelloWorld{public static void main(String[] args){System.out.println("hello world");}}
```
# 代码块-配置【不】启用行号
```java:no-line-numberspublic class HelloWorld{public static void main(String[] args){System.out.println("这是没有行号的代码块");}}
```

 补充 ： 指定行号的起始值

说明 ： 行号默认是从1开始的，如果想改变这个值，可以通过:line-numbers=n 的方式，直接指定行号从n开始 

• 代码聚焦

代码聚焦的效果是 ：凸显指定的内容，并模糊其他的部分，从而使重点突出。

基本语法 ：// [!code focus]

用法 ： 在需要聚焦的行后添加上述标注即可。
补充 ： // [!code focus:xxx] : xxx 是一个数字，代表要聚焦的行数

# 代码块-聚焦-单行
```javapublic class HelloWorld{public static void main(String[] args){System.out.println("hello world"); // [!code focus]}}
```# 代码块-聚焦-连续多行
```javapublic class HelloWorld{public static void main(String[] args){ // [!code focus:3]System.out.println("hello world");}}
```

• 删除/新增标记。

这个功能就类似于 git 中的代码的删除与新增的展示效果。

基本语法 ：
删除标注 ：// [!code --]
新增标注 ：// [!code ++]

# 代码块-删除/新增标记
```javapublic class HelloWorld{public static void main(String[] args){System.out.println("hello world"); // [!code --]System.out.println("hello new world"); // [!code ++]}}
```

• 代码错误/警告标记。

可以提示读者哪些代码有错误。这个功能的效果也是通过行的颜色来表示的。

基本语法 ：
错误标注 ：// [!code warning]
警告标注 ：// [!code error]

# 代码块-错误/警告标记
```javapublic class HelloWorld{public static void main(String[] args){System.out.println("hello world"); // [!code warning]System.out.println("hello new world"); // [!code error]}}
```

• 高级配置 

VitePress 使用 markdown-it 作为Markdown的渲染器。上述许多扩展是通过自定义插件实现。你可以通过 .vitepress/config.js中的markdown进一步定制markdown-it

module.exports = {markdown: {// options for markdown-it-anchoranchor: { permalink: false },// options for markdown-it-toctoc: { includeLevel: [1, 2] },config: (md) => {// use more markdown-it plugins!md.use(require('markdown-it-xxx'))}}
}

 三、在Markdown中使用vue

• 浏览器 API 访问限制

因为 VitePress 应用在生成静态构建时是通过 Node.js 服务端渲染的，因此所有 Vue 的使用必须符合编写通用代码的要求。简而言之，要确保只在beforeMount 或 mounted时访问浏览器/DOM 的接口。

 如果你在使用或展示非 SSR 友好(比如包含自定义指令)的组件，你就可以使用ClientOnly将其包裹。

<ClientOnly><NonSSRFriendlyComponent/>
</ClientOnly>

 注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题。 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入：

<script>
export default {mounted() {import('./lib-that-access-window-on-import').then((module) => {// use code})}
}
</script>

 如果你的模块export default一个 Vue 组件，那么你可以动态注册。

<template><component v-if="dynamicComponent" :is="dynamicComponent"></component>
</template><script>
export default {data() {return {dynamicComponent: null}},mounted() {import('./lib-that-access-window-on-import').then((module) => {this.dynamicComponent = module.default})}
}
</script>

• 插值表达式

你可以在Markdown文件中直接使用Vue的插值表达式来显示数据

<script setup>
import { ref } from 'vue'
const message = ref('Hello, VitePress with Vue 3!')
</script># 标题这里是插值表达式：{{ message }}

• 指令

Vue的指令也可以在Markdown文件中使用，比如v-if、v-for等

<script setup>
import { ref } from 'vue'
const isVisible = ref(true)
const items = ref(['Item 1', 'Item 2', 'Item 3'])
</script># 标题<div v-if="isVisible">这个div是可见的</div><ul><li v-for="item in items" :key="item">{{ item }}</li>
</ul>

• 组件

你可以在Markdown文件中导入并使用Vue组件

<script setup>
import MyComponent from './MyComponent.vue'
</script># 标题<MyComponent />

 在这里，MyComponent.vue是一个你定义好的Vue 3组件，它可以直接在Markdown文件中被引用和渲染。 

• 事件处理

你也可以在Markdown文件中为Vue组件添加事件处理

<script setup>
import { ref } from 'vue'
const count = ref(0)
function increment() {count.value++
}
</script># 标题<button @click="increment">点击次数：{{ count }}</button>

• 使用<script setup>

Vue 3引入了<script setup>语法糖，它允许你更简洁地编写组件逻辑。在VitePress的Markdown文件中，你也可以使用这种语法

<script setup>
// 在这里编写你的Vue 3逻辑
</script># 你的标题和内容// 在这里使用你的Vue 3组件和指令

 

注意事项 

确保你的VitePress配置支持Vue 3和Markdown的结合。通常，VitePress默认支持这个功能，但你可能需要检查并配置一些选项。
在Markdown文件中使用Vue语法时，确保你的Vue代码被正确地包裹在<script>标签内，并且遵循Vue 3的语法规则。
如果你使用的是自定义的Vue组件，请确保它们已经被正确地导入，并且可以在Markdown文件中被识别和使用。

• 访问站点及页面数据

编译后的组件可以访问 站点元数据和计算属性。

输入：

{{ $page }}

 输出：

• Escaping

默认情况下，代码块(三个反引号包裹)将会被自动包裹在 v-pre 中。如果你想要在内联 (inline) 的代码块或者普通文本中显示原始的大括号或一些 Vue 特定的语法，你需要使用自定义容器 v-pre来包裹：

 输入：

::: v-pre
`{{ This will be displayed as-is }}`
:::

输出：

 {{ This will be displayed as-is }}