边栏配置

Vergil 支持通过 src/data/config/features.ts 配置左右边栏的组件内容和顺序。

核心概念

边栏配置由三个字段配合完成：

left / right — 决定显示哪些组件、按什么顺序（UI 控制）
components — 为组件提供数据（数据配置）
nav — 左侧栏的站内导航菜单

两者的配合关系：

sidebar: {
    // left/right 里的每个 key，都需要在 components 中找到对应的配置
    left: ['recentPosts', 'siteInfo'],
    right: ['welcome', 'notice', 'heatmap', 'featured', 'tags'],
    
    // components 提供每个组件的数据
    components: {
        welcome,             // ← right 里的 'welcome' 需要这个
        notice,              // ← right 里的 'notice' 需要这个
        recentPosts: { limit: 5 },  // ← left 里的 'recentPosts' 需要这个
        featured: { limit: 3 },     // ← right 里的 'featured' 需要这个
        tags: { limit: 6 },         // ← right 里的 'tags' 需要这个
    },
}

规则：

left / right 中的 key 名在 components 中找不到配置 → 该位置不显示任何内容
components 中有配置但 left / right 中没有 → 只是不显示（不会报错）
heatmap 是唯一例外，不需要在 components 中配置

左侧栏

结构

左侧栏顶部是固定区域（不可移除）：

个人资料卡：头像、名字、副标题、社交图标

固定区域下方通过 left 数组和 nav 配置：

站内导航

通过 nav 数组配置，每个项包含 label（显示名）、href（链接）和 icon（图标名）：

nav: [
    { label: '首页', href: '/', icon: 'home' },
    { label: '博客', href: '/blog', icon: 'book-open' },
    { label: '专栏', href: '/series', icon: 'bookmark' },
    { label: '文档', href: '/docs', icon: 'book-text' },
    { label: '相册', href: '/albums', icon: 'image' },
    { label: '留言', href: '/contact', icon: 'message-circle' },
],

icon 使用 Lucide Icons 的图标名（kebab-case，如 book-open、message-circle）。你可以自定义数量、顺序、名称和图标。不配置时默认显示上述 6 项。

下方组件

通过 left 数组配置：

组件 ID	说明	`components` 配置
`recentPosts`	最近更新列表	`limit`（默认 5）
`siteInfo`	站点统计+备案信息	不需要

左侧栏示例

left: ['recentPosts', 'siteInfo']   // 显示最近文章 + 站点信息
left: ['siteInfo']                   // 只显示站点信息
left: []                             // 不显示任何组件

右侧栏

结构

右侧栏完全通过 right 数组配置，默认用于列表页（首页、归档、标签页等）。

可用组件

组件 ID	说明	是否需要 `components` 配置
`heatmap`	8 周写作热力图	不需要
`recentPosts`	最近更新列表	`limit`（默认 5）
`featured`	精选文章（isFeatured=true）	`limit`（默认 3）
`tags`	热门标签列表	`limit`（默认 6）
`ghCard`	GitHub 仓库/用户卡片	`mode`/`repo`/`user`
`toc`	文章目录（文档页/文章页可用）	不需要
任意 Memo 卡片	Memo 便签卡片	详见 Memo 便签卡片

Memo 便签卡片（如 welcome、notice）是用户自定义内容的卡片，key 名由你决定。主题自带了 welcome.ts 和 notice.ts 两个示例，你可以修改它们，也可以创建新的卡片。详见 Memo 便签卡片。

右侧栏示例

// 显示所有组件
right: ['welcome', 'notice', 'heatmap', 'featured', 'tags']

// 只显示 welcome 和精选文章
right: ['welcome', 'featured']

// 自定义 Memo 卡片 + 热力图
right: ['about', 'heatmap', 'tags']

调整顺序

right 数组中的顺序就是右侧边栏的渲染顺序：

right: ['featured', 'welcome', 'heatmap', 'tags']
// 渲染顺序：精选文章 → 欢迎卡片 → 热力图 → 标签

隐藏组件

从 right 数组中删除对应的 ID 即可隐藏：

right: ['welcome', 'featured', 'tags']  // 隐藏了 notice 和 heatmap

组件数据配置

每个组件需要的数据写在 sidebar.components 中。left / right 中的 key 名和 components 中的 key 名必须一致。

内置组件的配置

components: {
    // 最近文章：显示 5 篇
    recentPosts: { limit: 5 },
    
    // 精选文章：显示 3 篇
    featured: { limit: 3 },
    
    // 热门标签：显示 6 个
    tags: { limit: 6 },
    
    // GitHub 卡片（可选）
    ghCard: {
        mode: 'repo',        // 'repo' 或 'user'
        repo: 'user/repo',   // 仓库名
        // user: 'username', // 用户名（mode 为 user 时使用）
    },
}

Memo 便签卡片的配置

Memo 卡片的内容写在独立的配置文件中，然后在 components 中引用：

// src/data/config/about.ts
import type { MemoItem } from '../../types';

export const about = {
    title: '关于我',
    paragraphs: ['一名热爱技术的开发者...'],
    actions: [
        { text: '了解更多', href: '/about' },
    ],
} satisfies MemoItem;

// src/data/config/features.ts
import { welcome } from './welcome';
import { notice } from './notice';
import { about } from './about';

export const sidebar = {
    right: ['welcome', 'about', 'heatmap', 'featured', 'tags'],
    components: {
        welcome,     // ← 从 welcome.ts 导入
        notice,      // ← 从 notice.ts 导入（right 中没放，不显示）
        about,       // ← 从 about.ts 导入
        recentPosts: { limit: 5 },
        featured: { limit: 3 },
        tags: { limit: 6 },
    },
};

详见 Memo 便签卡片。

文章页/文档页右侧栏

文章页和文档页的右侧栏目前通过页面级 slot 覆盖实现，不走 right 配置数组：

文章页：文章目录（Toc） + 相关文章 + 精选文章
文档页：文章目录（Toc）

这些组件需要页面上下文（如当前文章的标题、标签），因此无法在全局配置中指定。

注意事项

draft: true 的文章不会出现在任何边栏组件中
如果文章数量不足，recentPosts 和 featured 会自动少显示
ghCard 需要配置正确的仓库/用户名才能正常获取数据