Lumi's 书台

SYUTOI

一方书台,安放所思。

归档

专栏与阅读顺序

文章目录
专栏目录 · 主题文档

所有分类默认都是专栏。主题自动汇总分类中的文章,提供完整章节目录、同专栏前后篇导航,无需逐个启用。此功能在 v0.5.0 标签之后加入;没有分类的文章保持普通文章导航。

默认行为与可选范围

默认配置如下,普通博客无需重复填写:

yaml
columns:
categories: all

如果只希望部分分类使用专栏,在博客 _config.syutoi.yml 中填写分类名称列表:

yaml
columns:
categories:
- 主题文档
- 技术笔记/Hexo

分类名称区分大小写,应与文章中的分类一致;这里不是分类 URL 或 slug。嵌套分类使用完整名称路径 父分类/子分类,避免同名子分类混淆。分类的路径仍由 Hexo 和 category_map 决定,不需要创建另一套目录页面。

保存后重启预览并重新生成。categories: [] 关闭全部专栏,恢复分类文章卡片与日期分页;指定列表时,不在列表中的分类也保留原来的卡片与分页。分类本身不会因为写入配置而自动创建,需先有文章归入该分类。

设置文章顺序

在文章 Front Matter 中填写:

yaml
---
title: 配置你的第一个站点
categories:
- 主题文档
column_order: 20
---

column_order 使用真正的有限数值,不要加引号。数字越小越靠前;建议采用 10、20、30,方便之后插入 15。显式填写顺序的文章排在未填写的文章前面;同值或均未填写时,按发布日期从早到晚排列,日期相同再按文章路径稳定排序。置顶字段 sticky 不改变专栏顺序。

专栏目录会自动包含分类及其子分类中的文章,不用维护标题和链接清单。修改文章标题、路径或排序后,重新生成即可同步更新。

多分类与单篇退出

如果文章属于多个已启用专栏,默认选择层级最深的分类;深度相同,在 all 模式下按分类完整名称稳定排序;指定列表时按 columns.categories 的配置顺序选择。可以显式指定主要专栏:

yaml
column: 技术笔记/Hexo
column_order: 30

column 必须是已启用且该文章确实属于的分类完整名称;填写不存在或不属于的分类不会创建专栏或自动改分类。该字段控制文章页展示哪个专栏;文章仍可出现在其他所属专栏的完整目录中。

需要从所有专栏目录退出的文章可设置:

yaml
column: false

它仍可在普通首页、归档等地方展示。草稿、published: false、带 password 的文章不会进入专栏目录;未来文章跟随站点 future 开关。这些规则不是访问控制,不能用于保护已经发布的页面。

页面如何展示

  • 桌面侧栏的目录标题行直接提供“本文目录 / 专栏目录”切换,不再重复显示面板标题;专栏目录高亮当前文章,导读与章节使用相同列表样式,导读不编号,不额外显示篇数位置。没有正文目录时直接显示专栏目录。
  • 手机正文前提供可折叠的专栏目录;关闭整个侧栏时,桌面也使用正文前的折叠入口。
  • 文末前后篇按照专栏顺序跳转,首篇没有上一篇,末篇没有下一篇;“查看完整专栏”返回专栏首页(无导读时为分类页)。
  • 默认所有分类页使用完整、紧凑的章节列表,不按日期分页;显式排除的分类保留卡片和分页。

sidebar.toc 和 sidebar.toc_number 只控制当前文章的标题目录,不关闭专栏目录,也不改变专栏的文章顺序。专栏列表的序号表示阅读位置,不等于 column_order 的原始数值。

浏览器会记住你选择的“本文目录 / 专栏目录”,切换文章或刷新后沿用;遇到只有一种目录的页面会显示可用目录,不覆盖偏好。禁用本地存储时仍可正常切换,但不保存选择。桌面切换标题保持固定,下方长目录可独立滚动,高度随窗口和目录位置调整。

无需 JavaScript 也能使用目录链接和手机折叠入口;桌面无 JS 时两份目录直接显示。键盘可通过 Tab 进入切换按钮,方向键、Home/End 切换面板。

专栏分类页列出全部章节,适合手册和教程;文章很多时可按主题拆成子分类专栏。启用后原有分类分页不再生成,部署时应同步清理旧文件,更新曾指向分类第二页的链接。

将导读与章节放在一起

在 _posts 下为专栏建一个目录,将导读写在 index.md 中,章节放在旁边:

text
source/_posts/
├── theme-docs/
│ ├── index.md
│ ├── getting-started.md
│ └── configuration.md
└── reading/
├── index.md
└── first-book.md

主题会将嵌套目录中的 index.md 识别为专栏首页,在导读正文之后自动显示完整章节目录。它不占章节序号,也不进入普通文章列表、归档、文章前后篇或订阅;搜索和站点地图仍可收录首页。无需额外维护独立 Page 或手写完整章节清单。

目录名仅用于整理文件,专栏归属仍由 Front Matter 的分类决定。导读和章节应填写相同分类。例如导读:

yaml
---
title: Syutoi 使用手册
categories:
- 主题文档
permalink: docs/
---

这里写专栏介绍、阅读建议或按需求推荐的入口。

permalink 可省略,此时首页直接使用该分类的标准地址(由 Hexo 的 category_dir、category_map 决定)。填写 permalink: docs/ 则将 /docs/ 作为专栏入口;主题中的分类链接和“查看完整专栏”都会指向它。原分类地址也能访问同一份导读与目录,并通过 canonical 标记指向专栏首页。

章节使用普通文章字段:

yaml
---
title: 基础配置
categories:
- 主题文档
permalink: docs/configuration/
column_order: 20
---

新增章节、修改标题和顺序后自动更新目录。没有 index.md 时,分类页仍显示完整章节目录;删除导读后也自动回到这一行为。Hexo server 支持直接监听这些 Markdown 文件,配置变动则需重启。

约定与边界

  • 每个专栏最多一个导读;重复导读或与现有文章、独立页面冲突的地址会令生成失败,并提示冲突文件。
  • 导读至少填写 categories;嵌套分类默认取最深一层。属于多个同层级分类时,用 column: 父分类/子分类 明确归属,避免首页被分配给错误专栏。
  • column: false 可让名为 index.md 的文件作为普通文章处理。未启用专栏的分类(例如 columns.categories: [])同样保留普通文章行为。
  • 不使用 _posts/index.md 作为专栏导读;请放在专栏子目录内。文件夹本身不会创建分类。
  • 草稿、未发布、带 password 的导读不生成专栏首页;未来日期遵循站点 future 设置。
  • 自定义首页地址应避开首页、归档、分类总览、标签总览等系统路径。调整地址或删除页面后,部署时同步清理旧生成文件。

示例站的主题文档

示例的导读与 13 篇指南均保存在 example/source/_posts/theme-docs/,其中 index.md 是使用手册首页。直接参照这些文件编写自己的专栏即可,不需要同步工具。

permalink 决定网站访问地址,与磁盘位置无关;/docs/configuration/ 对应的源文件就在该目录的 configuration.md 中。项目根目录 docs/ 只保留开发计划、设计记录与验收材料。


文档首页

查看完整专栏 · 主题文档