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 { /* 特定页面的样式 */ }
注意: 以上的配置可以通过$frontmatter
访问
---
title: Hello
---
# {{ $frontmatter.title }}
示例:
---
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
---
TOC
输入:
[[toc]]
输出:
目录列表
配置:
可以使用 markdown.toc
选项配置 TOC 的呈现效果。
markdown: {
toc: {
level: [2, 3, 4, 5, 6, 7, 8]
}
},
自定义容器
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
行高亮
行高亮
# 单行
```js {4}
```
# 多个单行
```js {4,7,9}
```
# 多行
```js {4-8}
```
# 多行与单行
```js {4,7-13,16,23-27,40}
```
!code
[!code highlight]: 行高亮
# 行高亮
```js
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
[!code focus]: 聚焦
[!code focus]
[!code focus:<lines>]
# 聚焦
```js
export default {
data () {
return {
msg: 'Focused!'
}
}
}
```
[!code --]: 颜色差异
[!code --]
[!code ++]
# 颜色差异
```js
export default {
data () {
return {
msg: 'Removed'
msg: 'Added'
}
}
}
```
[!code warning]: 警告
[!code error]: 错误
# 错误,警告
```js
export default {
data () {
return {
msg: 'Error',
msg: 'Warning'
}
}
}
```
行号
可以通过以下配置为每个代码块启用行号:
export default {
markdown: {
lineNumbers: true
}
}
导入代码片段
可以通过下面的语法来从现有文件中导入代码片段:
@/
: 表示绝对路径(也可以使用相对路径)#snippet
:表示代码文件中自定义的区域名js// #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 文件,甚至是内嵌的。
# 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
问题集
自定义JS代码
问题: 打包时报错:ReferenceError: document is not defined
分析: 这是因为在 .vitepress/theme/index.js
文件中在node环境中调用了document
解决: 将自定义代码放入 enhanceApp
函数中并使用 app.mixin()
来混入生命周期钩子mounted
来确保在浏览器加载后执行。
// 最终代码
// https://vitepress.dev/guide/custom-theme
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import './style.css'
/** @type {import('vitepress').Theme} */
export default {
extends: DefaultTheme,
Layout: () => {
return h(DefaultTheme.Layout, null, {
// https://vitepress.dev/guide/extending-default-theme#layout-slots
})
},
enhanceApp({ app, router, siteData }) {
// 自定义代码
app.mixin({
mounted() {
let els = document.querySelectorAll('.content a')
let hs = document.querySelectorAll('.content h1,h2,h3,h4,h5,h6,h7,h8')
els = Array.from(els)
hs = Array.from(hs)
const allEls = [...els, ...hs]
allEls.forEach((el) => {
// console.log(el.innerHTML, /^▸/.test(el.innerHTML))
if (/^▸/.test(el.innerHTML)) {
el.style.color = 'blue'
}
})
}
})
}
}