当前位置： 首页 > news >正文

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

news 2025/8/10 15:54:01

#上次总结的 有些语法是用在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 }}

http://www.lryc.cn/news/498158.html

相关文章：

  • Vue3技术开发，使用纯CSS3动手制作一个3D环绕的相册展示效果，支持传入任意图片.3D轮播相册的组件
  • LeetCode 力扣 热题 100道（十五）搜索插入位置（C++）
  • 【035】基于51单片机俄罗斯方块游戏机【Proteus仿真+Keil程序+报告+原理图】
  • NAT traversal 原理 | TCP / UDP/ P2P
  • 如何成长为一名工程技术经理
  • GEE开发之下载海拔、坡度、坡向数据
  • gozero项目迁移与新服务器环境配置,包含服务器安装包括go版本,Nginx,项目配置包括Mysql,redis,rabbit,域名
  • Scala正则表达式全面教程
  • 伺服电机为什么会变慢?
  • 61 基于单片机的小车雷达避障及阈值可调
  • 微信小程序之手机归属地查询
  • ElementUI 问题清单
  • DVWA靶场——XSS(Stored)
  • Spring框架中的Bean是线程安全的吗？
  • uniapp远程摄像头流界面上显示
  • elasticSearch（一）：elasticSearch介绍
  • 基于 RWKV 的视觉语言模型 VisualRWKV 被 COLING 2025 接收！
  • 输出九九乘法表:JAVA
  • kube-proxy的iptables工作模式分析
  • xiaolin coding 图解 MySQL笔记——锁篇
  • 11-SpringCloud Alibaba-Seata处理分布式事务
  • 更换 Git 项目的远程仓库地址（五种方法）
  • 3大模块助力学生会视频自动评审系统升级
  • 鸿蒙开发——使用ArkTs处理XML文本
  • 【Linux】文件查找 find grep
  • Go学习笔记之运算符号
  • npm : 无法加载文件 D:\nodejs\npm.ps1，因为在此系统上禁止运行脚本
  • YOLOv8-ultralytics-8.2.103部分代码阅读笔记-torch_utils.py
  • Java中的数据存储结构解析与应用
  • 【链表】力扣 141. 环形链表