vitepress-tree-hole

简述

vitepress-tree-hole 是一个基于 VitePress 的内容型博客主题，面向个人博客、长期笔记和项目文档混合维护的站点。主题提供博客首页、文章列表、分类标签、时间线、导航页、评论、碎片笔记、统计和季节飘落装饰等能力，并尽量把站点私有信息收敛到 themeConfig 中配置。

vitepress-tree-hole

vitepress 博客主题

安装

npm

$ npm i @night-tea/vitepress-tree-hole

pnpm

$ pnpm i @night-tea/vitepress-tree-hole

yarn

$ yarn add @night-tea/vitepress-tree-hole

使用

首先引入主题

// .vitepress/theme/index.ts
import theme from "@night-tea/vitepress-tree-hole";
export default {
  extends: theme,
  // ....
} satisfies Theme;

如果没有额外扩展的需求，也可以这样写

import theme from "@night-tea/vitepress-tree-hole";
export default theme;

在配置文件中，将defineConfig更换为defineConfigWithTheme,并引入基本配置

// .vitepress/config.mts
import { defineConfig } from "vitepress"; 
import { defineConfigWithTheme } from "vitepress"; 
import baseConfig from "@night-tea/vitepress-tree-hole/baseConfig"; 
export default defineConfigWithTheme<ThemeConfig>({
  extends: baseConfig, 
  // ...
})

文件结构

.
├─ .vitepress
|  ├─ theme
|  |  └─ index.ts
│  └─ config.mts
├─ blogs // [!code ++]
├─ docs // [!code ++]
└─ pages // [!code ++]
└─ package.json

使用该主题，需要约束一定的文件结构，本主题将所页面分为三种情况：博客，文档，页面，需要分别放在blogs 、docs pages这三个文件夹中，其中，这三者的区别是：

1. 博客会被文章列表获取，并会在blog页面中展示，也会在标签 分类 时间线中展示
2. 文档不会在文章列表中展示，适用于库的API文档等非博客类文档
3. 页面主要是那些做首页、导航、时间线灯页面的md文档

首页花园区

主题的博客首页会自动读取最新文章、分类数量和站点导航，并组合成首屏的内容入口。可以通过 homeGarden 指定优先展示的分类和快捷入口：

// .vitepress/config.mts
export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    homeGarden: {
      brandInitial: "站",
      featuredCategories: ["Web", "Life", "Notes"],
      featuredLinks: [
        { title: "文档", desc: "主题、组件和工具说明", link: "/docs" },
        { title: "归档", desc: "按时间浏览内容", link: "/timeline" },
      ],
    },
  },
})

featuredCategories 只决定首页优先级，不会创建分类；主题会从真实文章分类中匹配并补足。featuredLinks 可以指向站内路径或外部链接，不配置时会从 nav 中选择站内入口作为默认内容。

站点信息抽离

主题包不会内置个人博客、个人仓库或固定项目入口。页脚主题链接、首页标识、作者、头像、统计、评论和碎片笔记接口都需要在站点自己的 themeConfig 中配置：

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    author: "Your Name",
    authorImage: "/avatar.png",
    treeHoleFooter: {
      themeLink: {
        text: "vitepress-tree-hole",
        link: "https://github.com/example/vitepress-tree-hole",
      },
    },
  },
})

如果不配置 treeHoleFooter.themeLink，页脚不会显示主题项目按钮。

下一步

1. 创建本主题的页面
2. 设置本主题的配置