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

#上次总结的有些语法是用在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 { // Highlighted
  data () {
    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
  }
}

局部标记(推荐使用)

语法：

直接在代码块类型的后面添加 :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开始

代码聚焦

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

基本语法：// [!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]
        }
    }
```

高级配置

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

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },

    // options for markdown-it-toc
    toc: { 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 }}`
:::

输出：

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

一、基础Markdown语法

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

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

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

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

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

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

加粗和斜体。

分割线。

引用。

二、Markdown在vitepress使用扩展

内部链接。

页面后缀

外部链接

表情符号

自定义容器

自定义标题

行号

代码聚焦

删除/新增标记。

代码错误/警告标记。

高级配置

三、在Markdown中使用vue

浏览器 API 访问限制

插值表达式

指令

组件

事件处理

使用`<script setup>`

访问站点及页面数据

Escaping

网站公告

今日签到

热门文章

最新发布

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

一、基础Markdown语法

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

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

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

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

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

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

加粗和斜体。

分割线。

引用。

二、Markdown在vitepress使用扩展

内部链接。

页面后缀

外部链接

表情符号

自定义容器

自定义标题

行号

代码聚焦

删除/新增标记。

代码错误/警告标记。

高级配置

三、在Markdown中使用vue

浏览器 API 访问限制

插值表达式

指令

组件

事件处理

使用<script setup>

访问站点及页面数据

Escaping

网站公告

今日签到

热门文章

最新发布

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

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

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

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

使用`<script setup>`