布局

框架 API 目前默认支持以下布局，布局支持与最终表现通常与主题有关。

• post：文章布局
• tags：标签布局
• archives：归档布局
• categories：分类布局
• collections：合集布局

使用布局 ​

合集布局 ​

合集允许你将一系列相关文章（如小说、系列教程）组织为一个整体，并提供有序的导航。

目录结构 ​

pages/
  collections/
    index.md              # 合集总览页
    hamster/              # 一个合集
      index.ts            # 合集配置（必需）
      index.md            # 合集入口页
      1.md                # 文章 1
      2.md                # 文章 2
      to-be-or-not.md     # 使用字符串 key 的文章

1. 创建总览页 ​

新建 pages/collections/index.md，并指定布局为 collections：

---
layout: collections
icon: i-ri-gallery-view
collections:
  - hamster
  - love-and-peace
---

2. 创建合集 ​

新建合集文件夹 pages/collections/hamster/，包含以下文件：

• index.ts：合集配置文件（必需）。
• index.md：合集入口页。
• 1.md、2.md、…：合集中的文章。

新建入口页 pages/collections/hamster/index.md：

---
layout: collection
---

在 index.ts 中定义合集配置：

import { defineCollection } from 'valaxy'

export default defineCollection({
  key: 'hamster',
  title: '仓鼠',
  cover: 'https://cover.sli.dev',
  description: 'The story of I and She',
  items: [
    { title: '第一章 仓鼠的笼子', key: '1' },
    { title: '第二章 白昼之光，岂知夜色之深。', key: '2' },
    { title: '第三章 作茧自缚', key: '3' },
  ],
})

3. 创建文章 ​

layout: collection 可省略，pages/collections/ 目录下的所有文章默认使用 collection 布局。

---
title: 第一章 仓鼠的笼子
---

你的文章内容。

效果预览：合集 | Valaxy Theme Yun

CollectionConfig ​

折叠模式 ​

当 collapse 为 true（默认）时，合集在首页和归档文章列表中显示为一张卡片。由于合集文章位于 /collections/ 路径下，它们不会单独出现在文章列表中——折叠卡片提供了进入合集的便捷入口。

export default defineCollection({
  title: '我的系列',
  collapse: true, // 默认 — 显示为一张卡片
  items: [/* ... */],
})

当 collapse 为 false 时，不会在文章列表中添加合集条目。

export default defineCollection({
  title: '我的系列',
  collapse: false, // 不在文章列表中显示卡片
  items: [/* ... */],
})

链接外部内容 ​

你可以使用 link 字段在合集的阅读顺序中引用已有的博客文章或外部 URL。当合集包含不在合集目录中的内容时，这个功能非常有用。

• 内部链接（以 / 开头）通过 <RouterLink> 在站内导航。
• 外部链接（如 https://...）在新标签页中打开，并显示外部链接图标。
• key 与 link 互斥。若同时设置，link 优先。

export default defineCollection({
  title: '我的学习路径',
  items: [
    { title: '第一章 - 基础', key: '1' },
    { title: '相关博文', link: '/posts/my-related-article' },
    { title: '第二章 - 进阶', key: '2' },
    { title: '外部参考', link: 'https://example.com/resource' },
  ],
})

实现布局（主题开发者） ​

valaxy-theme-yun 自 v0.25.9 起支持 collections 布局。

按约定，主题需要在 layouts 目录下创建对应的布局文件，文件名与布局名称相同。

在主题中，你可以使用以下合集相关 API：

• useCollections() — 获取所有合集配置。
• useCollection() — 获取当前合集（根据路由路径判断）。
• useCollectionPosts(key) — 获取指定合集的文章列表，按 items 定义的顺序排列。
• usePostListWithCollections() — 获取合并了折叠合集条目的文章列表。

<script setup lang="ts">
import { useCollections, useFrontmatter, useValaxyI18n } from 'valaxy'
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const { $tO } = useValaxyI18n()
const fm = useFrontmatter()
const { collections } = useCollections()
</script>

<template>
  <YunLayoutWrapper>
    <YunLayoutLeft />

    <RouterView v-slot="{ Component }">
      <component :is="Component">
        <template #main-header>
          <YunPageHeader
            :title="$tO(fm.title) || t('menu.collections')"
            :icon="fm.icon"
            :page-title-class="fm.pageTitleClass"
          />
        </template>

        <template #main-content>
          <div flex="~ wrap" gap="6">
            <YunCollectionItem
              v-for="collection in collections"
              :key="collection.key"
              :collection="collection"
            />
          </div>
        </template>
      </component>
    </RouterView>
  </YunLayoutWrapper>
</template>

FAQ ​

子页面发生了多层布局嵌套 ​

Vue Router 的页面会自动嵌套父级布局，请参考 Nested Routes | Unplugin Vue Router。

例如将：

pages/users/create.vue 修改为 pages/users.create.vue。