Vitepress

[TOC]

TIP

官方文档：https://vitepress.dev/zh/guide/what-is-vitepress

视频教程：https://space.bilibili.com/162101364/channel/collectiondetail?sid=1844787&ctype=0

环境搭建

安装

TIP

环境：Node.js 18 及以上版本

版本：vitepress@1.3.1

1、安装 vitepress

$ pnpm add -D vitepress

2、安装向导

$ pnpm vitepress init

将需要回答几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Site title:
│  mr笔记
│
◇  Site description:
│
│
◆  Theme:
│  ○ Default Theme (Out of the box, good-looking docs)
│  ● Default Theme + Customization
│  ○ Custom Theme
└

文件结构

因为选择在./目录下建设站点，目录结构如下

.
│  api-examples.md
│  index.md
│  markdown-examples.md
│  vitepress.md

│  package.json
│  pnpm-lock.yaml
│
└─.vitepress # 当前目录所在的位置就是文档的根目录
    │  config.mjs # 项目的配置文件，最重要
    │
    └─theme # 主题目录
            index.js
            style.css

配置文件

配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

// .vitepress/config.js
export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

Markdown 扩展

frontmatter

title：string，页面的标题。它与 config.title 相同，并且覆盖站点级配置。
titleTemplate：string | boolean，标题的后缀。它与 config.titleTemplate 相同，它会覆盖站点级别的配置。
description：string，页面的描述。它与 config.description 相同，它会覆盖站点级别的配置。
head：HeadConfig[]，指定要为当前页面注入的额外 head 标签。将附加在站点级配置注入的头部标签之后。
layout：doc | home | page，默认：doc，指定页面的布局。
- doc：它将默认文档样式应用于 markdown 内容。
- home：“主页”的特殊布局。可以添加额外的选项，例如 hero 和 features，以快速创建漂亮的落地页。
- page：表现类似于 doc，但它不对内容应用任何样式。当想创建一个完全自定义的页面时很有用。
hero：home page only，当 layout 设置为 home 时，定义主页 hero 部分的内容。
features：home page only，定义当layout 设置为 home 时要在 features 部分中显示的项目。
navbar：boolean，默认：true，是否显示导航栏。
sidebar：boolean，默认：true，是否显示侧边栏。
aside：boolean | 'left'，默认：true，定义侧边栏组件在 doc 布局中的位置。
- 将此值设置为 false 可禁用侧边栏容器。
- 将此值设置为 true 会将侧边栏渲染到右侧。
- 将此值设置为 left 会将侧边栏渲染到左侧。
outline：number | [number, number] | 'deep' | false，默认：2，大纲中显示的标题级别。它与 config.themeConfig.outline.level 相同，它会覆盖站点级的配置。
lastUpdated：boolean | Date，默认：true，是否在当前页面的页脚中显示最后更新时间的文本。如果指定了日期时间，则会显示该日期时间而不是上次 git 修改的时间戳。
editLink：boolean，默认：true，是否在当前页的页脚显示编辑链接。
footer：boolean，默认：true，是否显示页脚。
pageClass：string，将额外的类名称添加到特定页面。然后可以在 .vitepress/theme/custom.css 文件中自定义该特定页面的样式。
css
```
.custom-page-class {
  /* 特定页面的样式 */
}
```
1
2
3

~~注意：~~ 以上的配置可以通过$frontmatter访问

---
title: Hello
---

# {{ $frontmatter.title }}

~~示例：~~

yaml

---
title: 文章标题

titleTemplate: Vite & Vue powered static site generator

description: VitePress

head:
  - - meta
    - name: description
      content: hello
  - - meta
    - name: keywords
      content: super duper SEO

layout: doc

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
  - icon:
      src: /cool-feature-icon.svg
    title: Another cool feature
    details: Lorem ipsum...
  - icon:
      dark: /dark-feature-icon.svg
      light: /light-feature-icon.svg
    title: Another cool feature
    details: Lorem ipsum...

navbar: true

sidebar: true

aside: true

lastUpdated: true

editLink: true

footer: true

pageClass: custom-page-class
---

自定义容器

info

::: info 自定义标题
This is an info box.
:::

> [!NOTE] 自定义标题
> 强调用户在快速浏览文档时也不应忽略的重要信息。

tip

::: tip 自定义标题
This is a tip.
:::

> [!TIP] 自定义标题
> 有助于用户更顺利达成目标的建议性信息。

important

> [!IMPORTANT] 自定义标题
> 对用户达成目标至关重要的信息。

warning

::: warning 自定义标题
This is a warning.
:::

> [!WARNING] 自定义标题
> 因为可能存在风险，所以需要用户立即关注的关键内容。

danger

::: danger 自定义标题
This is a dangerous warning.
:::

> [!CAUTION] 自定义标题
> 行为可能带来的负面影响。

details

::: details 自定义标题
This is a details block.
:::

全局设置自定义标题

可以通过在站点配置中添加以下内容 markdown.container.tipLabel 来全局设置自定义标题，如果不是用英语书写，这会很有帮助：

// config.ts
export default defineConfig({
  // ...
  markdown: {
    container: {
      tipLabel: '提示',
      warningLabel: '警告',
      dangerLabel: '危险',
      infoLabel: '信息',
      detailsLabel: '详细信息'
    }
  }
  // ...
})

语法高亮

常用的高亮语言：

c
cpp，c++
css
html
http
java
javascript，js
typescript，ts
json
jsx
tsx
less
sass
scss
markdown，md
php
postcss
python,py
regexp，regex
ruby，rb
shellscript，bash，sh，shell
sql
stylus,styl
vue
wasm
xml
yaml，yml

行高亮

yml

# 单行
```js {4}
```

# 多个单行
```js {4,7,9}
```

# 多行
```js {4-8}
```

# 多行与单行
```js {4,7-13,16,23-27,40}
```

!code

~~[!code highlight]：~~ 行高亮

yml


# 行高亮
```js
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

~~[!code focus]：~~ 聚焦

[!code focus]
[!code focus:<lines>]

yml

# 聚焦
```js
export default {
  data () {
    return {
      msg: 'Focused!'
    }
  }
}
```

~~[!code --]：~~ 颜色差异

[!code --]
[!code ++]

yml

# 颜色差异
```js
export default {
  data () {
    return {
      msg: 'Removed'
      msg: 'Added'
    }
  }
}
```

~~[!code warning]：~~ 警告

~~[!code error]：~~ 错误

yml

# 错误，警告
```js
export default {
  data () {
    return {
      msg: 'Error', 
      msg: 'Warning'
    }
  }
}
```

行号

可以通过以下配置为每个代码块启用行号：

export default {
  markdown: {
    lineNumbers: true
  }
}

导入代码片段

可以通过下面的语法来从现有文件中导入代码片段：

@/：表示绝对路径(也可以使用相对路径)

#snippet：表示代码文件中自定义的区域名

// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

{highlightLines}：表示行高亮
{highlightLines js}：中的 js 表示指定的语言

<<< @/filepath#snippet{highlightLines js}

代码组

可以像这样对多个代码块进行分组：

:::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
```

:::

包含 markdown 文件

可以像这样在一个 markdown 文件中包含另一个 markdown 文件，甚至是内嵌的。

yml

# Docs

## Basics

# 基本使用
<!--@include: ./parts/basics.md-->

# 使用绝对路径
<!--@include: @/docs/parts/basics.md-->

# 选择行范围,格式可以是：{3,}、 {,10}、{1,10}
<!--@include: ./parts/basics.md{3,}-->

parts/basics.md文件：

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

图片预览【

TODO: 添加图片预览功能：https://zichin.com/blog/1.VitePress/3.怎么给 vitepress 添加点击图片放大预览功能.html

Vitepress ​

环境搭建 ​

安装 ​

文件结构 ​

配置文件 ​

Markdown 扩展 ​

frontmatter ​

TOC ​

自定义容器 ​

info ​

tip ​

important ​

warning ​

danger ​

details ​

全局设置自定义标题 ​

语法高亮 ​

行高亮 ​