Vitepress + Cloudflare 操作指南

目的: vitepress + github私有仓库 + cloudflare实现文档管理

步骤简述:

在github创建私有仓库
拉取到本地后, 在本地仓库配置Vitepress相关环境, 添加自己编写的文档, 配置完成后推送到远端
在Cloudflare中配置Pages, 系统分配连接, 实现静态站点访问效果

步骤详述

github创建私有仓库

略

Vitepress本地环境配置

npm -v 检查时候安装npm, 如果未安装, 使用 brew install npm 安装npm
打开命令行, 进入本地仓库文件夹(下边的命令都在这目录执行), 初始化Vitepress npx vitepress init 根据安装向导进行即可 (默认位置选择/docs, 如果不是可能需要修改相关参数, 本文档都以存在docs为准)
安装vitepress依赖 npm i -D vitepress@latest

默认的侧边栏需要自己维护, 很麻烦, 所以需要使用到插件来自动维护目录, 安装侧边栏 vitepress-sidebar 插件插件安装后需要修改config.mts文件. 安装命令 npm install vitepress-sidebar -D . config.mts示例:

import { defineConfig } from 'vitepress'
import { generateSidebar } from 'vitepress-sidebar'; 

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "me title",
  description: "me desc",
  themeConfig: { 
    sidebar: generateSidebar({
      /* 常用配置选项 */
      documentRootPath: '/',       // 文档根目录
      scanStartPath: 'docs',      // 扫描的具体目录（如果你想只针对 guide 目录生成）
      resolvePath: '/docs/',      // 链接前缀
      useTitleFromFileHeading: true, // 是否使用 Markdown 文件内的一级标题(H1)作为名称
      useTitleFromFrontmatter: true, // 是否使用 frontmatter 中的 title 字段
      collapsed: true,            // 是否默认折叠
      collapseDepth: 1,            // 默认折叠深度
      sortMenusByName: false,       // 按照文件名排序
      // sortMenusByFrontmatterOrder: true,  按照index.md中的order进行排序

      // 将文件夹命名为 01-folder-3 和 02-folder-2。 这样侧边栏会按照 01, 02 排序，但在显示时会自动去掉数字前缀，只显示原名
      removePrefixAfterOrdering: true,
      prefixSeparator:"-" // 分割序号和文件夹名称的符号  0.5 也可以顺利排序, 说明是按照浮点排序, 并非只有int
    }), 
  }
})

运行服务 npx vitepress dev docs 访问网页查看和调试结果

侧边栏配置

关于文件排序还有其他的配置方案, 下边感觉是最简洁的. 通过改变文件夹的实际名称来强制排序。

将文件夹/文件命名为 01-folder-3 和 02-folder-2。这样侧边栏会按照 01, 02 排序，但在显示时会自动去掉数字前缀，只显示原名. 0.5 也可以顺利排序, 说明是按照浮点排序, 并非只有int.

// 常用配置项比较重要的两句
removePrefixAfterOrdering: true,
prefixSeparator:"-"

修改首页显示index.md模板的默认内容

删除默认所有内容, 或者删除或注释掉 layout: home, 这样就不会显示默认内容
把md当成你自己的文档编写内容就展示的是你自己的内容

创建自定义 CSS 文件

可能对Vitepress默认生成的样式不满意, 则需要自定义css

项目目录中创建.vitepress/theme/custom.css, 内容如下:

:root {
  /* --- 侧边栏整体字体大小 --- */
  --vp-sidebar-font-size: 9px; /* 默认通常是 13px 或 14px   这个不生效*/

  /* --- 调整行高 (Line Height) --- */
  /* VitePress 侧边栏主要通过 item 的 padding 来控制间距，而不仅是 line-height */
}

/* 调整侧边栏每一行的高度（通过上下内边距控制） */
.VPSidebarItem.level-0 {
  padding-top: 2px !important;
  padding-bottom: 2px !important;
}


/* 调整侧边栏子菜单中的每一行的高度（通过上下内边距控制） */
.VPSidebarItem.level-1,
.VPSidebarItem.level-2,
.VPSidebarItem.level-3 {
  padding-top: 4px !important;
  padding-bottom: 4px !important;
}

/* 如果想精准调整文字本身的行高 */
.VPSidebarItem .text {
  line-height: 1.2 !important;
  font-size: 15px; /* 这里也可以单独微调文字大小  这个不生效*/ 
}

/* 调整侧边栏分组标题（大标题）的文字大小和间距 */
.VPSidebarItem.level-0 .text {
  font-weight: 700;
  font-size: 10.5px;
  color: var(--vp-c-text-1);
}

项目目录中创建.vitepress/theme/index.ts, 确保引入了自定义的css文件内容如下:

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import './custom.css' // 引入你的自定义样式

export default {
  extends: DefaultTheme,
  // ... 其他配置
}

Vitepress + Cloudflare 操作指南 ​

步骤简述: ​

步骤详述 ​

github创建私有仓库 ​

Vitepress本地环境配置 ​

侧边栏配置 ​

修改首页显示index.md模板的默认内容 ​

创建自定义 CSS 文件 ​