Vitepress

1.什么是Vitepress

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。

简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

应用场景：个人博客、技术文档

2.创建项目

2.1 前置条件

Node.js18 及以上版本。
通过命令行界面 (CLI) 访问 VitePress 的终端。
支持Markdown语法的编辑器。
- 推荐 VSCode 及其官方 Vue 扩展。

2.2 创建项目

创建项目文件夹，并在项目根目录处打开终端

mkdir <projectName>
cd <projectName>

2.3 初始化项目

生成package.json

npm init -y

2.4 安装vitepress依赖

npmpnpmyarnbun

$ npm add -D vitepress

$ pnpm add -D vitepress

$ yarn add -D vitepress

$ bun add -D vitepress

2.5 初始化vitepress项目

npmpnpmyarnbun

$ npx vitepress init

$ pnpm vitepress init

$ yarn vitepress init

$ bun vitepress init

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

┌  Welcome to VitePress!	
│
◇  Where should VitePress initialize the config?					配置文件保存文件夹
│  ./docs
│
◇  Site title:														网站标题
│  My Awesome Project
│
◇  Site description:												网站描述
│  A VitePress Site
│
◇  Theme:															选择网站样式主题
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
│ 
◇  Use TypeScript for config and theme files?						是否使用Ts
│  No
│
◇  Add VitePress npm scripts to package.json?						是否在package.json中写入相关指令
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

Vue 作为 peer dependency

如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 vue 安装为 dependency。

2.6 文件结构

.
├─ docs								配置文件及文档存放目录
│  ├─ .vitepress					配置文件存档目录
│  │  └─ config.js					配置文件
│  ├─ api-examples.md				md文档案例
│  ├─ markdown-examples.md			md文档案例
│  └─ index.md						主页配置md文档
└─ package.json

docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

2.7 配置文件

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

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

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

2.8 源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。

VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。

VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些将在路由指南中进行介绍。

2.9 启动并运行

package.json 中我们可以看到相应的脚本

json

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

npmpnpmyarnbun

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ bun run docs:dev

除了 npm 脚本，还可以直接调用 VitePress：

npmpnpmyarnbun

$ npx vitepress dev docs

$ pnpm vitepress dev docs

$ yarn vitepress dev docs

$ bun vitepress dev docs

运行打开http://localhost:5173，我们可以看到出现如下页面

3.页面配置

3.1 首页界面

根目录的docs里，通过index.md配置首页界面样式及内容

markdown

---
layout: home
hero:
    name: Fade away
    tagline: 花有重开日，人无再少年
    image:
        src: /lufy.png
        alt: VitePress
    actions:
        - theme: brand
          text: VitePress
          link: /docs/vitepress
        - theme: alt
          text: 网址导航
          link: /docs/收藏的网站/index
features:
    - icon: ⚡️
      title: 首先，这是首先
    - icon: 🖖
      title: 其次，这是其次
    - icon: 🛠️
      title: 然后，就没啦
---

如下图所示

TIP

image图片应该放在docs里的public里，没有就新建，

config.mjs中要添加base:'/'

export default defineConfig({
	base: '/',
    // ...
})

3.2 导航栏

.vitepress/config.mjs文件中，通过配置themeConfig里的nav，来配置顶部导航

type NavItem = NavItemWithLink | NavItemWithChildren

interface NavItemWithLink {
    text: string
    link: string
    items?: never
    activeMatch?: string
    rel?: string
    target?: string
    noIcon?: boolean
}
export interface NavItemChildren {
    text?: string
    items: NavItemWithLink[]
}

export interface NavItemWithChildren {
    text?: string
    items: (NavItemChildren | NavItemWithLink)[]
    activeMatch?: string
}


const nav:NavItem[]=[]
themeConfig: {
    nav,
    // ...
}

我自己网站的

export default [
    {
        text: '前端',
        items: [
            {
                text: '前端三剑客',
                items: [
                    {
                        text: '🍉Html',
                        link: '/docs/前端/前端三剑客/Html/01.Html初识',
                    },
                    {
                        text: '🍊CSS',
                        link: '/docs/前端/前端三剑客/CSS/CSS/01.引入css样式表',
                    },
                    {
                        text: '🍇JavaScript',
                        link: '/docs/前端/前端三剑客/javascript/js基础/01.js基础语法',
                    },
                ],
            },
            {
                text: '框架',
                items: [
                    { text: '😺Vue', link: '/docs/前端/框架/Vue/Vue2/01.Vue基础' },
                    { text: '🐨React', link: '/docs/前端/框架/React/01.React入门' },
                ],
            },
            {
                text: '可视化',
                items: [
                    { text: '🍬Canvas', link: '/docs/前端/可视化/Canvas/01.认识Canvas' },
                    { text: '🍭WebGl', link: '/docs/前端/可视化/WebGL/01.WebGL基础' },
                    { text: '🍦Threejs', link: '/docs/前端/可视化/Three.js/01.基础用法' },
                ],
            },
            {
                text: '🛀小程序',
                link: '/docs/前端/小程序/01.mina.md',
            },
            {
                text: '⛵Webpack',
                link: '/docs/前端/Webpack/01.Webpack基础.md',
            },
        ],
    },
    {
        text: '后端',
        items: [
            {
                text: '🍔Node.js',
                link: '/docs/后端/Node.js/01.初识Node.js',
            },
            {
                text: '⚡C++',
                link: '/docs/后端/C++/01.环境配置',
            },
        ],
    },
    {
        text: '学习git',
        link: '/docs/学习git/git',
    },
    {
        text: '收藏网址',
        link: '/docs/收藏的网站/index',
    },
]

3.3 侧边栏

.vitepress/config.mjs文件中，通过配置themeConfig里的sidebar，来配置侧边栏导航

type Sidebar = SidebarItem[] | SidebarMulti

interface SidebarMulti {
    [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}

type SidebarItem = {
    text?: string
    link?: string
    items?: SidebarItem[]
    collapsed?: boolean
    base?: string
    docFooterText?: string
    rel?: string
    target?: string
}

4.部署github pages

4.1 添加.gitignore

vitepress创建的项目没有自动生成.gitignore文件，需要我们手动创建，不然会把node_modules等不需要的内容上传到github

根目录下创建.gitignore

.gitignore

node_modules
.DS_Store
dist
dist-ssr
cache
.cache
.temp
*.local

4.2 创建github仓库

github右上角New repository创建新仓库

TIP

若想最后的网站链接如xxxx.github.io形式，仓库名应设置为xxxx.github.io，xxxx应和github账号名一致，然后点击create repository

TIP

若部署的网站为子网站，即xxxx.github.io/yyyy格式，需要修改config.mjs中的base为'/yyyy/'

4.3 上传代码

在项目根目录下打开终端，或git bash，输入如下指令

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/xarzhi/xiazhi.git //切换为自己的仓库地址
git push -u origin main

4.4 设置pages部署形式

按步骤选择Setting=>pages=>Deploy from a branch=>GitHub Actions

4.5 创建工作流

4.5.1 github中创建

选择好Github Actions之后点击browse all workflows

或者从上方Actions处进入，之后点击set up a workflow yourself

复制以下内容，看情况修改部分内容

deploy.yml

yml

# Sample workflow for building and deploying a VitePress site to GitHub Pages
#
name: Deploy VitePress site to Pages

on:
    # Runs on pushes targeting the `main` branch. Change this to `master` if you're
    # using the `master` branch as the default branch.
    push:
        branches: [main]

    # Allows you to run this workflow manually from the Actions tab
    workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
    contents: read
    pages: write
    id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
    group: pages
    cancel-in-progress: false

jobs:
    # Build job
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0 # Not needed if lastUpdated is not enabled
            # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
            # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
            - name: Setup Node
              uses: actions/setup-node@v4
              with:
                  node-version: 20
                  cache: yarn # or pnpm / yarn
            - name: Setup Pages
              uses: actions/configure-pages@v4
            - name: Install dependencies
              run: yarn # or pnpm install / yarn install / bun install
            - name: Build with VitePress
              run: yarn run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
            - name: Upload artifact
              uses: actions/upload-pages-artifact@v3
              with:
                  path: docs/.vitepress/dist

    # Deployment job
    deploy:
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        needs: build
        runs-on: ubuntu-latest
        name: Deploy
        steps:
            - name: Deploy to GitHub Pages
              id: deployment
              uses: actions/deploy-pages@v4

复制好之后修改文件名为deploy.yml，也可以不改，改了好看

之后点击右上角commit changes...

然后点击commit changes

在此之后，仓库中会多一此commit记录，并且在项目根目录中会新增一个.github/workflows/deploy.yml文件，之后等待片刻再打开pages

4.5.2 项目中创建

除了上面方法，也可以直接在项目根目录创建.github/workflows/deploy.yml文件，复制上面deploy.yml内容，之后push代码进仓库

4.6 部署成功

再次进入Github pages页面，若部署成功，会显示我们的网站，点进去即可看到

以后每次更新内容，只用push代码，github会自动帮我们更新部署

效果

之后进入Actions界面，会显示每次的部署记录，若部署失败，可以点击进入查看失败原因

5.公共组件

5.1 单独使用

可以在md文件中直接使用一个script标签，使用vue3的语法导入相应的组件

test.md

markdown

<script setup>
import Test from './test.vue'
</script>


# 测试用例

<Test/>

5.2 公共组件

在.vitepress文件夹下创建theme文件夹，并创建index.js文件，写入如下内容

import DefaultTheme from 'vitepress/theme'
import Circle from "./compnents/Circle.vue";

export default {
    extends: DefaultTheme,
    enhanceApp({ app }) {
        // 注册自定义全局组件
        app.component("Circle", Circle);
    }
}

之后就可以直接在md文档中使用组件，使用方式和vue3中使用组件方式一样

6.markdown扩展

6.1 自定义容器

默认样式

markdown输入

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

Html输出

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之后附加文本来设置自定义标题

markdown输入

::: danger STOP
危险区域，请勿继续
:::

::: details 点我查看代码
```js
console.log('Hello, VitePress!')
```
:::

Html输出

STOP

危险区域，请勿继续

点我查看代码

console.log('Hello, VitePress!')

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

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

6.2 指定行高亮

基本语法

语法如下，也就是通过在{}填入相应的行号

markdown

```js {4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

效果如下所示

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

多行高亮

除了单行之外，还可以指定多个单行、多行，或两者均指定：

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

markdown

```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'
    }
  }
}
```

如下所示

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] 注释实现行高亮。

markdown

```js
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

效果如下

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

6.3 代码块聚焦

在某一行上添加 // [!code focus] 注释将聚焦它并模糊代码的其他部分。

```js								// [!code focus]
export default {					// [!code focus]
  data () {							// [!code focus]
    return {						// [!code focus]
      msg: 'Focused!' 				// // [!code focus] [!code focus]
    }								// [!code focus]
  }									// [!code focus]
}									// [!code focus]
```									// [!code focus]

效果如下

export default {
  data () {
    return {
      msg: 'Focused!'
    }
  }
}

6.4 代码块中的颜色差异

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

export default {
  data () {
    return {
      msg: 'Removed'
      msg: 'Added'
    }
  }
}

6.5 高亮“错误”和“警告”

在某一行添加 // [!code warning] 或 // [!code error] 注释将会为该行相应的着色。

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

6.6 行号

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

config.js

export default {
  markdown: {
    lineNumbers: true
  }
}

查看 markdown 选项获取更多信息。

可以在代码块中添加 :line-numbers / :no-line-numbers 标记来覆盖在配置中的设置。

还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，例如 :line-numbers=2 表示代码块中的行号从 2 开始。



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

效果如下

// 默认禁用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'

6.5 代码组

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

:::

效果如下

config.jsconfig.ts

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

6.5 图片懒加载

export default {
  markdown: {
    image: {
      // 默认禁用；设置为 true 可为所有图片启用懒加载。
      lazyLoading: true
    }
  }
}

Vitepress ​

1.什么是Vitepress ​

2.创建项目 ​

2.1 前置条件 ​

2.2 创建项目 ​

2.3 初始化项目 ​

2.4 安装vitepress依赖 ​

2.5 初始化vitepress项目 ​

2.6 文件结构 ​

2.7 配置文件 ​

2.8 源文件 ​

2.9 启动并运行 ​

3.页面配置 ​

3.1 首页界面 ​

3.2 导航栏 ​

3.3 侧边栏 ​

4.部署github pages ​

4.1 添加.gitignore ​

4.2 创建github仓库 ​

4.3 上传代码 ​

4.4 设置pages部署形式 ​

4.5 创建工作流 ​

4.5.1 github中创建 ​

4.5.2 项目中创建 ​

4.6 部署成功 ​

5.公共组件 ​

5.1 单独使用 ​

5.2 公共组件 ​

6.markdown扩展 ​

6.1 自定义容器 ​

默认样式 ​

自定义标题 ​

6.2 指定行高亮 ​

基本语法 ​

多行高亮 ​

通过注释实现 ​

6.3 代码块聚焦 ​

6.4 代码块中的颜色差异 ​

6.5 高亮“错误”和“警告” ​

6.6 行号 ​

6.5 代码组 ​

6.5 图片懒加载 ​

Vitepress

1.什么是Vitepress

2.创建项目

2.1 前置条件

2.2 创建项目

2.3 初始化项目

2.4 安装vitepress依赖

2.5 初始化vitepress项目

2.6 文件结构

2.7 配置文件

2.8 源文件

2.9 启动并运行

3.页面配置

3.1 首页界面

3.2 导航栏

3.3 侧边栏

4.部署github pages

4.1 添加.gitignore

4.2 创建github仓库

4.3 上传代码

4.4 设置pages部署形式

4.5 创建工作流

4.5.1 github中创建

4.5.2 项目中创建

4.6 部署成功

5.公共组件

5.1 单独使用

5.2 公共组件

6.markdown扩展

6.1 自定义容器

默认样式

自定义标题

6.2 指定行高亮

基本语法

多行高亮

通过注释实现

6.3 代码块聚焦

6.4 代码块中的颜色差异

6.5 高亮“错误”和“警告”

6.6 行号

6.5 代码组

6.5 图片懒加载