安装

提示

主题尚未发布 npm 包，目前只支持手动安装

全新安装（推荐）

若全新安装，建议直接 Clone / Fork Github 仓库作为模板

安装到现有 VitePress

信息

安装主题不会影响现有的 VitePress 正常运行(部分 CSS 样式会被覆盖)，可以放心安装

安装依赖

pnpm add @bprogress/core @fancyapps/ui @fontsource/geist-mono @fontsource/geist-sans @iconify/vue fast-glob gray-matter less medium-zoom remove-markdown -D

下载主题

1. 将 Github 仓库中的 src 文件夹复制到你的 VitePress 根目录中
2. 将 .vitepress/theme/ThemeLayout.vue 复制到你的 VitePress 对应位置
3. 将 .vitepress/theme/index.ts 复制到你的 VitePress 对应位置

必要配置

以下配置均在 .vitepress/config.ts 中

导入主题类型

导入 defineConfig 与 ThemeConfig

.vitepress/config.ts

import { defineConfig } from 'vitepress';
import type { ThemeConfig } from '../src/types';

export default defineConfig<ThemeConfig>({});

导入文章列表

导入 usePosts 方法，该方法用于获取博客的所有文章并生成文章列表，可以传入一个对象进行自定义配置，详见 usePosts 配置

返回的 posts 为文章列表，rewrites 为 VitePress 自带的路由重写功能，可用于重写文章的链接，本主题用 rewrites 实现永久链接功能，详见永久链接配置

.vitepress/config.ts

import { usePosts } from '../src/composables/usePosts';

const { posts, rewrites } = await usePosts({});

主题配置

在 themeConfig 对象中进行主题的配置，详见 themeConfig 。其中 posts 的配置项是必须的，该项由 usePosts 返回

最小化配置

.vitepress/config.ts

import { defineConfigWithTheme } from 'vitepress';
import { usePosts } from '../src/composables/usePosts';
import type { ThemeConfig } from '../src/types';

const { posts, rewrites } = await usePosts({});

export default defineConfigWithTheme<ThemeConfig>({
  rewrites,
  themeConfig: {
    posts
  }
});

标准配置

为了启用主题的所有功能（加密、草稿、隐藏、描述、信息等），还需要做亿点点配置

.vitepress/config.ts

import { defineConfig } from 'vitepress';
import { usePosts } from '../src/composables/usePosts';
import { hashPassword } from '../src/utils/hashPassword';
import type { ThemeConfig } from '../src/types';

// 文章列表页、分类页、归档页的自定义插槽
const slot = `
<template #doc-after>
  <AdItem :custom="ads" type="doc" />
</template>
`;

const custom = `
<script lang="ts" setup>
import AdItem from '/src/components/AdItem.vue';
import { ads } from '/.vitepress/theme/ads.ts';
</script>
`;

const { posts, hiddenPosts, excludePosts, descriptionMap, rewrites } = await usePosts({
  excerpt: 150,
  slot,
  custom
});

export default defineConfig<ThemeConfig>({
  rewrites,
  lastUpdated: true,
  // 隐藏文章
  sitemap: {
    hostname: 'https://domain.com',
    transformItems: (items) => {
      return items.filter((item) => !hiddenPosts.has(item.url.replace(/\.html$/, '')));
    }
  },
  transformPageData(pageData) {
    const { frontmatter, description } = pageData;
    const { id, password } = frontmatter;

    // 加密文章
    if (password) {
      frontmatter.password = hashPassword(String(password));
    }

    // 文章描述
    if (!description) {
      pageData.description = descriptionMap.get(id) as string;
    }
  },
  themeConfig: {
    posts,
    page: {
      max: 5
    },
    transition: true
  },
  markdown: {
    lineNumbers: true,
    config: (md) => {
      // 文章信息
      md.use((md) => {
        md.renderer.rules.heading_close = (tokens, idx, options, env, slf) => {
          let htmlResult = slf.renderToken(tokens, idx, options);
          if (tokens[idx].tag === 'h1') htmlResult += `<PostMeta />`;
          return htmlResult;
        };
      });
    }
  },
  // 草稿
  srcExclude: [...excludePosts]
});

启动

通过 pnpm dev 启动，首次运行后，会根据文章目录以及子目录中的所有 Markdown 文件在根目录中生成 index.md page-1.md page-2.md 等文件，这些 Markdown 文件将作为引导页或文章列表。

因此博客的所有文章需要创建在文章目录下（默认为 posts 目录，可在 usePosts 方法参数中进行修改，详见 usePosts。目录下的每个 Markdown 文件代表一篇文章，还需要在文章顶部添加 Frontmatter 用于描述文章标题、发布时间等等。

而其余目录的 Markdown 文件，则作为文档，在 .vitepress/config.ts 中为其配置 Sidebar 即可。

更新

提示

主题尚未发布 npm 包，目前只支持手动更新

复制 Github 仓库最新版中的 src 文件夹覆盖旧版本 src 文件夹即可