AsyncX's Library

Appearance

前言 ​

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

安装 ​

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

前置准备 ​

sh
npm add -D vitepress

安装向导 ​

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

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

一切顺利的话运行

sh
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

之后进行构建即可。

DANGER

你需要关闭Cloudflare的网页压缩加速功能！不然会删掉部分的Vue格式导致文件加载异常！

配制 ​

为主页标题添加彩色字 ​

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

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

安装 ​

sh
npm i -D vitepress-sidebar

配制 ​

修改.vitepress/config.js

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后你就会发现侧边栏已自动更新.

自定义主页 ​

学了约一天的Vue, 可以一知半解的给自己写个Homepage. 目前的主页代码:

markdown
---
title: Home
aside: false
outline: false
comments: false
progress: false
sidebar: false
next: false
version: v1.0
description: 阅读/技术/心得 存放处
---

<script setup lang="ts">
import Home from '.vitepress/theme/components/VHome.vue';
</script>

<Home />

除了Vitepress本身约定的yaml, 我自定义模板来方便配制.

vue
<script setup lang="ts">
import {useData,withBase} from 'vitepress'
const {site,frontmatter} = useData()
</script>

<template>
<header class="home-hero">
<figure class="figure">
<img class="image" src="./logo.svg" alt="logo" />
</figure>
<h1 class="title">AsyncX's Library<sub style="font-weight: 500; font-size: 1.5rem;">{{frontmatter.version}}</sub></h1>
<p class="description">
{{ frontmatter.description }}
</p>
<div class="actions">
<a href="/01-intro/design"><button class="btn">开始</button></a>
</div>
</header>
</template>