私有扩展

私有扩展指的是由 VitePress 定义或由本仓库定义的 Markdown 扩展语法。

本文使用 VitePress 标记由 VitePress 提供的私有语法，使用 Repo 标记本仓库提供的私有语法。VitePress 私有语法此处只列举一些常用的，更多内容请参阅 VitePress 文档：Markdown 扩展。

折叠块 VitePress

使用 ::: details xxx 标记折叠块。其中的 xxx 可略去，默认标题为 “Details”。

markdown

::: details 折叠块标题
被折叠的内容。
:::

渲染结果

折叠块标题

被折叠的内容。

代码块行高亮 VitePress

行高亮

在代码块语言标签后添加一对花括号 {}，在其中可指定高亮行，接受语法：

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

```js{4,7,9}
// ...
```

示例

输入

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

输出

export default {
  data() {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: "VitePress is awesome",
      lorem: "ipsum",
    };
  },
};

错误与警告

在行结尾添加 // [!code error] 或 // [!code warning] 可高亮错误行或警告行。

示例

输入

```js
export default {
  data () {
    return {
      msg: 'Error', // [!code error]
      msg: 'Warning' // [!code warning]
    }
  }
}
```

输出

export default {
  data() {
    return {
      msg: "Error", 
      msg: "Warning", 
    };
  },
};

Diff

在行结尾添加 // [!code --] 或 // [!code ++] 会为该行创建 diff，同时保留代码块的颜色。

示例

输入

```js
export default {
  data() {
    return {
      msg: "Removed", // [!code --]
      msg: "Added", // [!code ++]
    };
  },
};
```

输出

export default {
  data() {
    return {
      msg: "Removed", 
      msg: "Added", 
    };
  },
};

TIP

也支持直接高亮 diff。

diff

@@ -1,4 +1,4 @@
-import Worker from 'web-worker';
+// import Worker from 'web-worker';
 export var BackpressureStrategy;
 (function (BackpressureStrategy) {
     BackpressureStrategy["None"] = "none";

代码块行号 VitePress

在语言标签后添加 :line-numbers 可启用代码块行号（允许在标签与 : 间添加空格，也可以不加）。还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，例如 :line-numbers=2 表示代码块中的行号从 2 开始。

```ts :line-numbers
const line2 = "This is line 1";
```

```ts:line-numbers=5
const line2 = "This is line 5";
```

渲染结果

const line2 = "This is line 1";

const line2 = "This is line 5";

例题 Repo

使用 ::: example 标记例题。例题将会在同一篇文章中自动编号。

也可以使用 ::: example 来覆盖小标题内容。小标题被覆盖的例题块独立编号。

编号时，若全文只有一个，则编号自动省略。

markdown

::: example
一道例题
:::

::: example 引例
一道例题
:::

::: example
一道例题
:::

::: example 引例
一道例题
:::

渲染结果

例 1

一道例题

引例 1

一道例题

例 2

一道例题

引例 2

一道例题

徽章 Repo

本仓库提供 14 个颜色的徽章。

基本语法：

vue

<Tag text="文本" color="red" />
<T text="文本" color="red" />
<T t="文本" c="red" />
<T t="文本" red />
<Tag red>文本</Tag>
<T red>文本</T>

上面四种均合法，可自行取用。

Tag 标签可简写为 T，标记标签元素。
text 属性可简写为 t，定义徽章显示的文本内容。此外，也接受作为标签的内容传入。
color 属性可简写为 c，定义徽章的颜色。还可以直接将颜色名称作为属性名，组件会自动识别。下面是颜色与名称的对照表：

颜色	名称	颜色	名称
红色	`red`	粉色	`pink`
橙色	`orange`	洋红	`magenta`
黄色	`yellow`	青绿	`lime`
绿色	`green`	橄榄	`olive`
蓝色	`blue`	青色	`cyan`
靛青	`indigo`	茶色	`teal`
紫色	`purple`	灰色	`gray`

拼音 Repo

提供 Pinyin 或 PY 标签来在指定文本上方展示拼音。此外，也可以用于其他需要在文字上方加注内容的场合。支持自动加注或手动指定。基本语法：

markdown

<Pinyin>拼音</Pinyin>可以加注在<PY>字</PY>或词的上方。

渲染为：拼音()可以加注在字()或词的上方。

此外可以使用 manual 属性（简写为 m）来手动指定拼音内容。例如为日语中的汉字加注读音：

markdown

<PY m="まつす">松過</PY>ぎの
　<PY m="また">又</PY>も<PY m="こういん">光陰</PY>
　<PY m="や">矢</PY>の<PY m="ごと">如</PY>く

渲染为：松過()ぎの　又()も光陰() 　矢()の如()く

了解更多

此标签在编译时会转换为 HTML <ruby> 元素（MDN Docs）。这是 HTML5 引入的规范，相对较新，在不支持的浏览器上会 fallback 到括号加注的形式。有关其对齐规则，可以以此为关键字自行查找资料。

自动拼音加注采用的是 pinyin.js，并采用 Intl.Segmenter 分词来处理多音字。不能保证标注准确。

黑幕 Repo

使用 %% 包裹文字可隐藏文字内容，使用鼠标悬浮 / 触摸屏轻触可显示文字内容。使用场景包括习题答案 / 玩梗等。

markdown

不学习感觉自己未来要完蛋了，%%一学习确定自己未来要完蛋了%%。

渲染为：不学习感觉自己未来要完蛋了，一学习确定自己未来要完蛋了。

灵感来源于萌娘百科。

图片反色 Repo

图片反色提供一种简易的适配暗色模式的方式。

默认情况下，暗色模式中所有的图片会加上一个反色滤镜，以使观感和谐。

对于一些对颜色敏感的图片，例如照片、表情等，应在 alt 属性中添加 &keep-color

markdown

不反色的图片：
![&keep-color](./images/xxx.jpg)

在本地编辑器中应用此特性

如果你正在使用暗色模式，你需要在本地编辑器的 CSS 中添加如下代码：

css

img:not([alt*="&keep-color"]) {
  filter: invert(100%) hue-rotate(180deg) contrast(80%);
}

图片大小控制 Repo

部分示意图分辨率较高，导致图片显示过大，挤占其他内容的空间。但内容不多，无需占用这么大的空间。

在图片的 alt 属性中：

添加 &medium，将限制图片的最大高度为 300px。
添加 &small，将限制图片的最大高度为 200px。
添加 &smaller，将限制图片的最大高度为 120px。
添加 &tiny，将限制图片的最大高度为 80px。

markdown

![&small 图片描述](./images/xxx.jpg)

在本地编辑器中应用此特性

你需要在本地编辑器的 CSS 中添加如下代码：

css

img[alt*="&medium"] {
  max-height: 300px;
}
img[alt*="&small"] {
  max-height: 200px;
}
img[alt*="&smaller"] {
  max-height: 120px;
}
img[alt*="&tiny"] {
  max-height: 80px;
}

函数图像 Repo

仓库定义的 graph 代码块可在不依赖外部资源（例如 GeoGebra 或 Desmos 提供的 iframe）的情况下创建交互式的二维图像。graph 块中的配置使用 JSON5 格式书写。此功能使用 Function Plot 库实现，配置文件接口也与该项目相同。

你可以在项目官网查看例子，在 API 文档查看完整的接口。

Function Plot GUI 提供了图形界面编辑器，并可以直接输出 JSON5 格式的配置信息。需要注意的是，Function Plot GUI 项目还在完善中，并不能覆盖所有配置。

markdown

```graph
{
  data: [{ fn: "x^2" }],
}
```

渲染结果

将官网上的实例迁移到 Markdown 中

例如，对于官网上的例子：

functionPlot({
  target: "#derivative-update",
  yAxis: { domain: [-1, 9] },
  data: [
    {
      fn: "x^2",
      derivative: {
        fn: "2 * x",
        updateOnMouseMove: true,
      },
    },
  ],
});

插入 Markdown 中时，只保留花括号及其包裹的部分，并删去 target 字段。（target 字段用于指定函数图像插入的目标 DOM 元素，在 Markdown 渲染过程中会被覆盖）

markdown

```graph
{
  yAxis: { domain: [-1, 9] },
  data: [
    {
      fn: "x^2",
      derivative: {
        fn: "2 * x",
        updateOnMouseMove: true,
      },
    },
  ],
}
```

渲染结果：

WARNING

由于 Function Plot 的渲染依赖浏览器 API，因此无法进行 SSR（服务器端渲染），只能在前端渲染。因此如果配置中存在错误，无法在构建时发现。

请在确保函数图像可以正确渲染后再插入。

Baseline Repo

前端功能兼容性速查卡片。接受一个 feature 属性，传入值为 webstatus.dev 上的功能 ID，显示类似 MDN Web Docs 文档开头处的卡片。

兼容性情况将在用户访问页面时实时调用 API 查询。不必担心时效性。

vue

<Baseline feature="request-animation-frame" />
<Baseline feature="nesting" />
<Baseline feature="text-spacing-trim" />
<Baseline feature="abracadabra" />

Baseline status of request-animation-frame

Fetching baseline info...

Could not fetch information about this feature. Try searching on Can I Use or MDN Web Docs for more information.

Learn More　 See full compatibility

Baseline status of nesting

Fetching baseline info...

Could not fetch information about this feature. Try searching on Can I Use or MDN Web Docs for more information.

Learn More　 See full compatibility

Baseline status of text-spacing-trim

Fetching baseline info...

Could not fetch information about this feature. Try searching on Can I Use or MDN Web Docs for more information.

Learn More　 See full compatibility

Baseline status of abracadabra

Fetching baseline info...

Could not fetch information about this feature. Try searching on Can I Use or MDN Web Docs for more information.

Learn More　 See full compatibility

CADPA 内容分级 Repo 整活

根据 CADPA 提供的分级标准，提供 4 种适龄提示贴纸。

12+

16+

18+

语法：

vue

<CADPA age="8" />
<CADPA age="12" />
<CADPA age="16" />
<CADPA age="18" />

age 属性只接受这四个值。

私有扩展 ​

折叠块 VitePress ​

代码块行高亮 VitePress ​

行高亮 ​

错误与警告 ​

Diff ​

代码块行号 VitePress ​

例题 Repo ​

徽章 Repo ​

拼音 Repo ​

黑幕 Repo ​

图片反色 Repo ​

图片大小控制 Repo ​

函数图像 Repo ​

Baseline Repo ​

CADPA 内容分级 Repo 整活 ​

私有扩展

折叠块 VitePress

代码块行高亮 VitePress

行高亮

错误与警告

Diff

代码块行号 VitePress

例题 Repo

徽章 Repo

拼音 Repo

黑幕 Repo

图片反色 Repo

图片大小控制 Repo

函数图像 Repo

Baseline Repo

CADPA 内容分级 Repo 整活