inkpaper 主题介绍与快速上手

inkpaper 是一个 VitePress 博客主题。视觉上就一句话：纸白墨黑，朱砂点缀。

做这个主题的想法很简单——个人日志不需要花哨的设计，需要的是安静、可读、有质感。市面上大多数博客主题要么过于工程化，要么视觉上太吵，我想要的是打开页面就像摊开一张宣纸。

安装

npm install @inkpaper/vitepress

主题依赖 VitePress >= 1.0.0 和 Vue >= 3.3.0，这两个是 peerDependencies，你的项目里应该已经有了。

快速开始

最快的方式是用脚手架工具：

npx @inkpaper/create-for-vitepress my-blog
cd my-blog
npm install
npm run dev

这会在 my-blog 目录下生成完整的项目结构：VitePress 配置、主题入口、首页/归档/标签页面、内容加载器、一篇示例文章。直接跑就能看到效果。

在 docs/posts/ 下写文章，Frontmatter 至少要有 title、date、tags 三个字段：

---
title: 我的第一篇文章
date: 2026-05-11
tags:
  - 随笔
---

正文内容。

date 决定排序，tags 用于标签页筛选和相关文章推荐。支持子目录分类。

如果你已有 VitePress 项目，往下看手动配置。

手动配置

四个步骤，分别解决不同的问题。

1. 内容加载器

VitePress 本身不知道怎么从 Markdown 文件里提取文章列表——它只负责渲染单篇页面。内容加载器告诉它如何扫描文章目录、从 frontmatter 里提取标题、日期、标签，生成一份结构化的文章数据供主题组件使用。

docs/posts.data.ts：

import { createPostsLoader } from '@inkpaper/vitepress/loader'

export default createPostsLoader()

默认扫描 posts/**/*.md，如果文章不在这个路径下，传一个自定义 glob：createPostsLoader('articles/**/*.md')。

2. 主题入口

VitePress 的主题入口负责把主题组件和数据绑到一起。inkpaper 的组件（首页、归档、标签等）需要文章数据才能工作，这一步把上面加载器生成的数据注入进去。

docs/.vitepress/theme/index.ts：

import theme, { themeEnhance } from '@inkpaper/vitepress'
import type { Theme } from 'vitepress'
import { data as posts } from '../../posts.data'

export default {
  ...theme,
  enhanceApp(ctx) {
    theme.enhanceApp?.(ctx)
    themeEnhance({ posts })(ctx)
  }
} satisfies Theme

如果你有相关文章的 JSON 数据，可以一起传进去：themeEnhance({ posts, related: relatedData })。不传数据也不会报错——主题默认注入空数组，页面能正常渲染，只是没有文章列表。

3. VitePress 配置

站点的基本信息和侧边栏导航在这里定义。title 和 description 会显示在首页标题和副标题上，generateSidebar 根据文章目录自动生成侧边导航。

docs/.vitepress/config.mts：

import { defineConfig } from 'vitepress'
import path from 'node:path'
// @ts-ignore — .mjs export
import { generateSidebar } from '@inkpaper/vitepress/config'

const postsDir = path.resolve(import.meta.dirname, '..', 'posts')

export default defineConfig({
  title: 'My Blog',
  description: 'A personal journal',
  themeConfig: {
    sidebar: generateSidebar(postsDir),
  }
})

generateSidebar 的默认行为是文章页显示目录树、归档页显示日期树、标签页不显示侧边栏。这些都可以配置，功能详解里会讲。

4. 页面文件

VitePress 是文件路由——有 .md 文件才有对应的 URL。主题提供了首页、归档、标签三个组件，但不能自动注册路由，需要你手动创建对应的 Markdown 文件来挂载它们。

docs/index.md：

---
layout: doc
title: 首页
---

<script setup>
import { HomeLayout } from '@inkpaper/vitepress'
</script>

<HomeLayout />

docs/archive/index.md：

---
title: 归档
sidebar: true
---

<script setup>
import { ArchivePage } from '@inkpaper/vitepress'
</script>

<ArchivePage />

docs/tags.md：

---
title: 标签
sidebar: true
---

<script setup>
import { TagsPage } from '@inkpaper/vitepress'
</script>

<TagsPage />

到这里就能跑了。npm run dev 启动开发服务器，打开浏览器看效果。

源码

GitHub: Moonshile/inkpaper-theme