vitepress组件库文档项目 markdown语法大全

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

一、基础Markdown语法

VitePress支持标准的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 |

• 加粗和斜体。

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

• 分割线。

---

• 引用。

> 这是一个引用。

• 展示行号。

/ ** 
默认情况下，vitepress 中的代码块是不展示行号的。
展示行号有两种方式：
方式一 ： 全局配置文件中配置 lineNumbers:true 属性
方式二 ：代码块中添加 :line-numbers / :no-line-numbers 标记来启用或禁用行号,这种方式会覆盖方式一的配置。
**/

// 方式一：全局配置 config中增加
markdown:{
   lineNumbers:true
}

// 方式二：局部标记(推荐使用)
// 语法 ：
// 直接在代码块类型的后面添加 :line-numbers 即表示开启行号
// 直接在代码块类型的后面添加 :no-line-numbers 即表示关闭行号展示

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

 补充 ： 指定行号的起始值

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

• 指定代码行高亮

代码块的作用是将块内的内容进行高亮展示，区别于其他的文本。
在代码块中，也可以指定某些行高亮，突出重点的代码行。
具体的表现就是 ： 指定的行就像多了阴影一样。

语法格式 ： 在 :line-numbers 之后添加 {xxx}即可
指定单行 ： {5} : 表示底行高亮
指定多行：{2-5} : 表示 第2到第5行 高亮
指定多个单行 ：{2,3,8} : 表示 第2第3第8行 高亮
单行与多行混合 ：{2,3,6-8} : 表示 第2第3 第6到第8行 高亮

# 代码块-行高亮-单行
```java:line-numbers {2}
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("hello world");
        }
    }
```

# 代码块-行高亮-多行
```java:line-numbers {2-4}
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("hello world");
        }
    }
```

# 代码块-行高亮-多个单行
```java:line-numbers {2,4}
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("hello world");
        }
    }
```

# 代码块-行高亮-单行与多行混合
```java:line-numbers {1,3-5}
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("hello world");
        }
    }
```

• 代码聚焦。

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

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

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

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

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

• 删除/新增标记。

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

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

# 代码块-删除/新增标记
```java
    public 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]

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

二、md文件中使用vue3语法扩展

在VitePress项目中，你可以在Markdown（.md）文件中嵌入Vue 3的组件和语法，这是VitePress的一个强大特性，它允许你将Markdown与Vue无缝结合来编写文档。以下是一些具体的Vue 3写法示例，以及如何在VitePress的Markdown文件中使用它们

• 插值表达式

你可以在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文件中被识别和使用。