622 lines
12 KiB
Markdown
622 lines
12 KiB
Markdown
---
|
||
layout: doc
|
||
title: VitePress 笔记使用
|
||
date: 2025-01-20
|
||
tags:
|
||
- 学习
|
||
- VitePress
|
||
- Blog
|
||
- Markdown
|
||
editLink: false
|
||
lastUpdated: 2025-01-20T10:09:34
|
||
head:
|
||
- - meta
|
||
- name: description
|
||
content: 本文介绍了如何使用 vitepress
|
||
---
|
||
|
||
> :black_nib: 文章摘要
|
||
|
||
<!-- DESC SEP -->
|
||
本文介绍了如何使用 vitepress
|
||
<!-- DESC SEP -->
|
||
|
||
## 内部链接
|
||
内部链接将转换为单页导航的路由链接。此外，子目录中包含的每个 `index.md` 都会自动转换为 `index.html`，并带有相应的 URL `/`。
|
||
[vitepress-link-jump](vitepress-link-jump.md) <!-- 可以添加 .md -->
|
||
```html
|
||
[VitePress 链接跳转](./VitePress 链接跳转.md)
|
||
```
|
||
|
||
## YAML front matter
|
||
任何包含 [YAML](https://yaml.org/) front matter 块的文件都将是 由 Jekyll 作为特殊文件处理。前言必须是第一件事 ，并且必须采用在三短划线 线。下面是一个基本示例：
|
||
|
||
``` markdown
|
||
---
|
||
layout: post
|
||
title: Blogging Like a Hacker
|
||
---
|
||
```
|
||
|
||
### frontmatter 配置
|
||
|
||
示例：
|
||
``` markdown
|
||
---
|
||
title: Docs with VitePress
|
||
editLink: true
|
||
---
|
||
```
|
||
可以通过 Vue 表达式中的 `$frontmatter` 全局变量访问 frontmatter 数据：
|
||
|
||
``` Vue
|
||
{{ $frontmatter.title }}
|
||
```
|
||
|
||
> 该内容由 Vue 渲染： **{{ $frontmatter.title }}**
|
||
|
||
|
||
## head
|
||
|
||
- 类型：`HeadConfig[]`
|
||
|
||
指定要为当前页面注入的额外 head 标签。将附加在站点级配置注入的头部标签之后。
|
||
|
||
yaml
|
||
|
||
``` markdown
|
||
---
|
||
head:
|
||
- - meta
|
||
- name: description
|
||
content: hello
|
||
- - meta
|
||
- name: keywords
|
||
content: super duper SEO
|
||
---
|
||
```
|
||
|
||
|
||
## layout
|
||
|
||
- 类型：`doc | home | page`
|
||
- 默认值：`doc`
|
||
|
||
指定页面的布局。
|
||
|
||
- `doc`——它将默认文档样式应用于 markdown 内容。
|
||
- `home`——“主页”的特殊布局。可以添加额外的选项，例如 `hero` 和 `features`，以快速创建漂亮的落地页。
|
||
- `page`——表现类似于 `doc`，但它不对内容应用任何样式。当想创建一个完全自定义的页面时很有用。
|
||
|
||
|
||
``` yaml
|
||
---
|
||
layout: doc
|
||
---
|
||
```
|
||
|
||
|
||
## navbar
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
是否显示导航栏。
|
||
|
||
``` yaml
|
||
---
|
||
navbar: false
|
||
---
|
||
```
|
||
|
||
## sidebar
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
是否显示 侧边栏
|
||
|
||
```
|
||
---
|
||
sidebar: false
|
||
---
|
||
```
|
||
|
||
## aside
|
||
|
||
- 类型：`boolean | 'left'`
|
||
- 默认值：`true`
|
||
|
||
定义侧边栏组件在 `doc` 布局中的位置。
|
||
|
||
将此值设置为 `false` 可禁用侧边栏容器。
|
||
将此值设置为 `true` 会将侧边栏渲染到右侧。
|
||
将此值设置为 `left` 会将侧边栏渲染到左侧。
|
||
|
||
```yaml
|
||
---
|
||
aside: false
|
||
---
|
||
```
|
||
|
||
## lastUpdated
|
||
|
||
- 类型：`boolean | Date`
|
||
- 默认值：`true`
|
||
|
||
是否在当前页面的页脚中显示最后更新时间的文本。如果指定了日期时间，则会显示该日期时间而不是上次 git 修改的时间戳。
|
||
|
||
``` yaml
|
||
---
|
||
lastUpdated: false
|
||
---
|
||
```
|
||
|
||
|
||
> [!TIP]
|
||
> 你必须提交 markdown 文件才能看到最后更新时间。
|
||
|
||
## Emoji
|
||
|
||
输入：
|
||
```html
|
||
:tada: :100:
|
||
```
|
||
输出：
|
||
|
||
:tada: :100:
|
||
## 自定义容器
|
||
自定义容器可以通过它们的类型、标题和内容来定义。
|
||
|
||
**输入**
|
||
|
||
```md
|
||
::: info
|
||
This is an info box.
|
||
:::
|
||
|
||
::: tip
|
||
This is a tip.
|
||
:::
|
||
|
||
::: warning
|
||
This is a warning.
|
||
:::
|
||
|
||
::: danger
|
||
This is a dangerous warning.
|
||
:::
|
||
|
||
::: details
|
||
This is a details block.
|
||
:::
|
||
```
|
||
|
||
**输出**
|
||
::: info
|
||
This is an info box.
|
||
:::
|
||
|
||
::: tip
|
||
This is a tip.
|
||
:::
|
||
|
||
::: warning
|
||
This is a warning.
|
||
:::
|
||
|
||
::: danger
|
||
This is a dangerous warning.
|
||
:::
|
||
|
||
::: details
|
||
This is a details block.
|
||
:::
|
||
|
||
## 自定义标题
|
||
可以通过在容器的 "type" 之后附加文本来设置自定义标题。
|
||
|
||
**输入**
|
||
|
||
``` md
|
||
::: danger STOP
|
||
危险区域，请勿继续
|
||
:::
|
||
|
||
::: details 点我查看代码
|
||
```js
|
||
console.log('Hello, VitePress!')
|
||
```
|
||
**输出**
|
||
|
||
::: danger STOP
|
||
危险区域，请勿继续
|
||
:::
|
||
|
||
::: details 点我查看代码
|
||
```js
|
||
console.log('Hello, VitePress!')
|
||
```
|
||
:::
|
||
|
||
## GitHub 风格的警报
|
||
|
||
```markdown
|
||
> [!NOTE]
|
||
> Useful information that users should know, even when skimming content.
|
||
|
||
> [!TIP]
|
||
> Helpful advice for doing things better or more easily.
|
||
|
||
> [!IMPORTANT]
|
||
> Key information users need to know to achieve their goal.
|
||
|
||
> [!WARNING]
|
||
> Urgent info that needs immediate user attention to avoid problems.
|
||
|
||
> [!CAUTION]
|
||
> Advises about risks or negative outcomes of certain actions.
|
||
```
|
||
|
||
> [!NOTE]
|
||
> Useful information that users should know, even when skimming content.
|
||
|
||
> [!TIP]
|
||
> Helpful advice for doing things better or more easily.
|
||
|
||
> [!IMPORTANT]
|
||
> Key information users need to know to achieve their goal.
|
||
|
||
> [!WARNING]
|
||
> Urgent info that needs immediate user attention to avoid problems.
|
||
|
||
> [!CAUTION]
|
||
> Advises about risks or negative outcomes of certain actions.
|
||
|
||
## 在代码块中实现行高亮
|
||
**输入**
|
||
```` md
|
||
```js{4}
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Highlighted!'
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
|
||
```js{4}
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Highlighted!'
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
除了单行之外，还可以指定多个单行、多行，或两者均指定：
|
||
|
||
- 多行：例如 `{5-8}`、`{3-10}`、`{10-17}`
|
||
- 多个单行：例如 `{4,7,9}`
|
||
- 多行与单行：例如 `{4,7-13,16,23-27,40}`
|
||
|
||
**输入**
|
||
```` md
|
||
```js{1,4,6-8}
|
||
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'
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
```js{1,4,6-8}
|
||
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'
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
也可以使用 `// [!code highlight]` 注释实现行高亮。
|
||
**输入**
|
||
````
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Highlighted!' // [!code highlight]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Highlighted!' // [!code highlight]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
## 代码块中聚焦
|
||
|
||
在某一行上添加 `// [!code focus]` 注释将聚焦它并模糊代码的其他部分。
|
||
此外，可以使用 `// [!code focus:<lines>]` 定义要聚焦的行数。
|
||
|
||
|
||
**输入**
|
||
|
||
````
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Focused!' // [!!code focus]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Focused!' // [!code focus]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 代码块中的颜色差异 {#colored-diffs-in-code-blocks}
|
||
|
||
在某一行添加 `// [!code --]` 或 `// [!code ++]` 注释将会为该行创建 diff，同时保留代码块的颜色。
|
||
|
||
**输入**
|
||
|
||
````
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Removed' // [!!code --]
|
||
msg: 'Added' // [!!code ++]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Removed' // [!code --]
|
||
msg: 'Added' // [!code ++]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 高亮“错误”和“警告” {#errors-and-warnings-in-code-blocks}
|
||
|
||
在某一行添加 `// [!code warning]` 或 `// [!code error]` 注释将会为该行相应的着色。
|
||
|
||
**输入**
|
||
|
||
````
|
||
```js
|
||
export default {
|
||
data () {
|
||
return {
|
||
msg: 'Error', // [!!code error]
|
||
msg: 'Warning' // [!!code warning]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
|
||
```js
|
||
export default {
|
||
data() {
|
||
return {
|
||
msg: 'Error', // [!code error]
|
||
msg: 'Warning' // [!code warning]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 行号 {#line-numbers}
|
||
|
||
可以通过以下配置为每个代码块启用行号：
|
||
|
||
```js
|
||
export default {
|
||
markdown: {
|
||
lineNumbers: true
|
||
}
|
||
}
|
||
```
|
||
|
||
查看 [`markdown` 选项](../reference/site-config#markdown) 获取更多信息。
|
||
|
||
可以在代码块中添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖在配置中的设置。
|
||
|
||
还可以通过在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块中的行号从 2 开始。
|
||
|
||
**输入**
|
||
|
||
````md
|
||
```ts {1}
|
||
// 默认禁用行号
|
||
const line2 = 'This is line 2'
|
||
const line3 = 'This is line 3'
|
||
```
|
||
|
||
```ts:line-numbers {1}
|
||
// 启用行号
|
||
const line2 = 'This is line 2'
|
||
const line3 = 'This is line 3'
|
||
```
|
||
|
||
```ts:line-numbers=2 {1}
|
||
// 行号已启用，并从 2 开始
|
||
const line3 = 'This is line 3'
|
||
const line4 = 'This is line 4'
|
||
```
|
||
````
|
||
|
||
**输出**
|
||
|
||
```ts {1}
|
||
// 默认禁用行号
|
||
const line2 = 'This is line 2'
|
||
const line3 = 'This is line 3'
|
||
```
|
||
|
||
```ts:line-numbers {1}
|
||
// 启用行号
|
||
const line2 = 'This is line 2'
|
||
const line3 = 'This is line 3'
|
||
```
|
||
|
||
```ts:line-numbers=2 {1}
|
||
// 行号已启用，并从 2 开始
|
||
const line3 = 'This is line 3'
|
||
const line4 = 'This is line 4'
|
||
```
|
||
|
||
## 代码组 {#code-groups}
|
||
|
||
可以像这样对多个代码块进行分组：
|
||
|
||
**输入**
|
||
|
||
````md
|
||
::: code-group
|
||
|
||
```js [config.js]
|
||
/**
|
||
* @type {import('vitepress').UserConfig}
|
||
*/
|
||
const config = {
|
||
// ...
|
||
}
|
||
|
||
export default config
|
||
```
|
||
|
||
```ts [config.ts]
|
||
import type { UserConfig } from 'vitepress'
|
||
|
||
const config: UserConfig = {
|
||
// ...
|
||
}
|
||
|
||
export default config
|
||
```
|
||
|
||
:::
|
||
````
|
||
|
||
**输出**
|
||
::: code-group
|
||
|
||
```js [config.js]
|
||
/**
|
||
* @type {import('vitepress').UserConfig}
|
||
*/
|
||
const config = {
|
||
// ...
|
||
}
|
||
|
||
export default config
|
||
```
|
||
|
||
```ts [config.ts]
|
||
import type { UserConfig } from 'vitepress'
|
||
|
||
const config: UserConfig = {
|
||
// ...
|
||
}
|
||
|
||
export default config
|
||
```
|
||
:::
|
||
|
||
|
||
## 数学方程 {#math-equations}
|
||
|
||
现在这是可选的。要启用它，需要安装 `markdown-it-mathjax3`，在配置文件中设置`markdown.math` 为 `true`：
|
||
|
||
```sh
|
||
npm add -D markdown-it-mathjax3
|
||
```
|
||
|
||
```ts [.vitepress/config.ts]
|
||
export default {
|
||
markdown: {
|
||
math: true
|
||
}
|
||
}
|
||
```
|
||
|
||
**输入**
|
||
|
||
```md
|
||
When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
|
||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||
|
||
**Maxwell's equations:**
|
||
|
||
| equation | description |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
|
||
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
|
||
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
|
||
```
|
||
|
||
**输出**
|
||
|
||
When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
|
||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||
|
||
**Maxwell's equations:**
|
||
|
||
| equation | description |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
|
||
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
|
||
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
|
||
|