第二期-Vitepress配制指南

#实用工具 #vitepress

前言

前段时间用Docsify感觉侧边栏的并不舒服，不想用md渲染html，但是没想到Vitepress的速度可以这么快。

Library

安装

我的包管理本来打算用npm + yarn（npm实在一言难尽），但在部署到Cloudflare上的时候出现了冲突。因此本指南统一使用npm部署到Cloudflare进行。如果你只想获得更多有用的配制，请转到：配制

前置准备

Terminal window
npm add -D vitepress

安装向导

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

Terminal window
npx vitepress init

默认如下，注意./docs和Default Theme + Customization为后续的默认配制.

┌  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
└

一切顺利的话运行

Terminal window
npm run docs:dev

即可在本地的http://localhost:5173看到网页。

部署到Cloudflare

在官方的配制教程里是简单带过的：

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render​

使用仪表板创建新项目并更改这些设置：

  • 构建命令： npm run docs:build
  • 输出目录： docs/.vitepress/dist
  • node 版本： 18 (或更高版本) 这里详细说一下用Cloudflare的Pages部署 构建命令依旧，构建输出目录依旧，我在手动为环境变量添加NODE_VERSION=18.0的时候部署失败了。因此建议在本地Vitepress项目文件夹根目录创建.nvmrc
18.17.0

之后进行构建即可。

配制

为主页标题添加彩色字

前文的创建中我的建议是自定义部分css。 编辑.vitepress/theme/style.css的line: 473/474

.vitepress/theme/style.css
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #53ffe2, #9d25d9);
--vp-home-hero-image-background-image: none;
--vp-home-hero-image-filter: none;
}

为Vitepress添加自动侧边栏

Github: vitepress-sidebar

安装

Terminal window
npm i -D vitepress-sidebar
npm i -D vitepress-sidebar

配制

修改.vitepress/config.js

.vitepress/config.js
sidebar:
sidebar: generateSidebar({ //自动sidebar
  text: 'Guide',
  items: [
    { text: 'Introduction', link: '/introduction' },
    { text: 'Getting Started', link: '/getting-started' }
  ]
  collapsed: true, //自动折叠
  documentRootPath: '/docs', //自动读取根目录
  useTitleFromFrontmatter: true, //读取fontmatter的标题属性,如果没有使用文件名
})

重新运行npm run docs:dev后你就会发现侧边栏已自动更新.

🫵🏻 随便看看
⬆︎Say something to me.⬆︎