🛠️ Twilight 主題：如何在側邊欄目錄新增「隨筆」板塊 (SOP)

說明：當你在主題中建立了全新的獨立板塊（例如「隨筆」）後，你會發現它預設並不會出現在左側的目錄樹（Directory Widget）中。這是因為目錄組件的資料獲取邏輯是寫死的。

本指南將教你如何修改目錄生成工具，讓「隨筆」以及其底下的所有資料夾，都能完美顯示在側邊欄中。

🎯 核心目標

修改目錄資料生成的工具檔案，手動將我們新建的 notes 集合（Collection）注入到目錄樹中，並確保它支援多層級資料夾嵌套以及正確的絕對路徑跳轉。

📂 修改目標檔案

請在你的專案中找到並打開以下檔案： 👉 src/utils/directory.ts

🛠️ 具體修改步驟

1. 引入原生獲取工具

在檔案最頂部的 import 區域，確保你引入了 Astro 原生的 getCollection 方法：

1
import { getCollection } from "astro:content";

2. 註冊根節點名稱

在 getDirectoryTree 函數內，找到 rootMap 物件。在這裡為你的新板塊設定一個要在側邊欄顯示的「頂級資料夾名稱」（此處設定為繁體字的「隨筆」）：

1
    const rootMap = {
2
        posts: i18n(I18nKey.posts),
3
        // ... 其他原有的分類
4
        timeline: i18n(I18nKey.timeline),
5
        // 👇 新增這一行
6
        notes: "隨筆",
7
    };

3. 抓取資料並注入目錄樹 (支援無限層級)

在處理完 posts 的 for 迴圈下方，新增一段專門處理 notes 的邏輯。

⚠️ 關鍵邏輯說明：

必須使用 fullSlug 來保留帶有資料夾層級的完整路徑（例如 diary/2026/test），否則點擊會跳轉到 404。
必須將 rootMap.notes 作為陣列的第一項，確保它歸類在「隨筆」這個大資料夾下。

1
    // --- 處理隨筆 (Notes) ---
2
    const allNotes = await getCollection("notes");
3
    for (const note of allNotes) {
4
        if (note.data.draft) continue; // 隱藏草稿
5

6
        // 1. 分割 ID 獲取資料夾層級
7
        const parts = note.id.split('/');
8
        const fileName = parts.pop()!;
9

10
        // 2. 獲取不含副檔名的完整相對路徑，確保跳轉正確
11
        const fullSlug = note.id.replace(/\.[^/.]+$/, "");
12

13
        // 3. 構建目錄樹層級：["隨筆", "子資料夾1", "子資料夾2"...]
14
        const paths = [rootMap.notes, ...parts];
15

16
        // 4. 將節點加入樹中 (確保 URL 使用絕對路徑 /notes/...)
17
        addNode(
18
            paths,
19
            note.data.title || fileName.replace(/\.[^/.]+$/, ""),
20
            `/notes/${fullSlug}/`
21
        );
22
    }

✅ 完整程式碼參考 (替換即可)

1
import { getSortedPosts } from "./post";
2
import { sortedAlbums } from "./albums";
3
import { sortedMoments } from "./diary";
4
import { projectsData } from "./projects";
5
import { skillsData } from "./skills";
6
import { timelineData } from "./timeline";
7
import { i18n } from "../i18n/translation";
8
import I18nKey from "../i18n/i18nKey";
9
// 引入 Astro 原生获取集合的方法
10
import { getCollection } from "astro:content";
11

12
export interface DirectoryNode {
13
    name: string;
14
    type: 'folder' | 'file';
15
    url?: string;
16
    children?: DirectoryNode[];
17
}
18

19
export async function getDirectoryTree(): Promise<DirectoryNode[]> {
20
    const rootMap = {
21
        posts: i18n(I18nKey.posts),
22
        albums: i18n(I18nKey.albums),
23
        diary: i18n(I18nKey.diary),
24
        projects: i18n(I18nKey.projects),
25
        skills: i18n(I18nKey.skills),
26
        timeline: i18n(I18nKey.timeline),
27
        // 在此处添加“随笔”分类在目录树中的根显示名称
28
        notes: "隨筆",
29
    };
30

31
    const tree: Record<string, any> = {};
32

33
    function addNode(paths: string[], name: string, url: string) {
34
        let current = tree;
35
        for (const part of paths) {
36
            if (!current[part]) {
37
                current[part] = { name: part, type: 'folder', children: {} };
38
            }
39
            current = current[part].children;
40
        }
41
        current[name] = { name, type: 'file', url };
42
    }
43

44
    // --- 1. 处理主博客文章 (Posts) ---
45
    const posts = await getSortedPosts();
46
    for (const post of posts) {
47
        if (post.data.draft) continue;
48
        const parts = post.id.split('/');
49
        const fileName = parts.pop()!;
50
        const paths = [rootMap.posts, ...parts];
51
        addNode(paths, post.data.title || fileName, `/posts/${post.id}/`);
52
    }
53

54
    // --- 2. 处理随笔 (Notes) - [核心修改：支持子文件夹及正确路径] ---
55
    const allNotes = await getCollection("notes");
56
    for (const note of allNotes) {
57
        if (note.data.draft) continue;
58

59
        // 分割 ID 获取文件夹层级
60
        const parts = note.id.split('/');
61
        // 弹出文件名
62
        const fileName = parts.pop()!;
63

64
        // 核心修复：获取不含后缀的完整相对路径 (如 "diary/2026/test")
65
        const fullSlug = note.id.replace(/\.[^/.]+$/, "");
66

67
        // 构建目录树层级：[“随笔”, "子文件夹1", "子文件夹2"...]
68
        const paths = [rootMap.notes, ...parts];
69

70
        // 将节点加入树中：
71
        // 参数 1: 文件夹层级
72
        // 参数 2: 显示名称 (优先用标题，没有则用去后缀的文件名)
73
        // 参数 3: 跳转 URL (必须以 /notes/ 开头并包含完整路径)
74
        addNode(
75
            paths,
76
            note.data.title || fileName.replace(/\.[^/.]+$/, ""),
77
            `/notes/${fullSlug}/`
78
        );
79
    }
80

81
    // --- 3. 处理相册 (Albums) ---
82
    for (const album of sortedAlbums) {
83
        if (!album.visible) continue;
84
        const basePathParts = album.basePath?.split('/') || [];
85
        if (basePathParts[0] === 'content') basePathParts.shift();
86
        if (basePathParts[0] === 'albums') basePathParts[0] = rootMap.albums;
87
        addNode(basePathParts, album.title || album.id, `/albums/${album.id}/`);
88
    }
89

90
    // --- 4. 处理日记 (Diary) ---
91
    for (const moment of sortedMoments) {
92
        const basePathParts = moment.basePath?.split('/') || [];
93
        if (basePathParts[0] === 'content') basePathParts.shift();
94
        if (basePathParts[0] === 'diary') basePathParts[0] = rootMap.diary;
95
        addNode(basePathParts, moment.title || moment.id, `/diary/`);
96
    }
97

98
    // --- 5. 处理项目 (Projects) ---
99
    for (const project of projectsData) {
100
        const basePathParts = project.basePath?.split('/') || [];
101
        if (basePathParts[0] === 'content') basePathParts.shift();
102
        if (basePathParts[0] === 'projects') basePathParts[0] = rootMap.projects;
103
        addNode(basePathParts, project.title || project.id, `/projects/`);
104
    }
105

106
    // --- 6. 处理技能 (Skills) ---
107
    for (const skill of skillsData) {
108
        const basePathParts = skill.basePath?.split('/') || [];
109
        if (basePathParts[0] === 'content') basePathParts.shift();
110
        if (basePathParts[0] === 'skills') basePathParts[0] = rootMap.skills;
111
        addNode(basePathParts, skill.name || skill.id, `/skills/`);
112
    }
113

114
    // --- 7. 处理时间线 (Timeline) ---
115
    for (const item of timelineData) {
116
        const basePathParts = item.basePath?.split('/') || [];
117
        if (basePathParts[0] === 'content') basePathParts.shift();
118
        if (basePathParts[0] === 'timeline') basePathParts[0] = rootMap.timeline;
119
        addNode(basePathParts, item.title || item.id, `/timeline/`);
120
    }
121

122
    // 将对象结构的树转换为前端组件需要的数组结构
123
    // function toArray(obj: Record<string, any>): DirectoryNode[] {
124
    //     const arr = Object.values(obj).map(node => {
125
    //         if (node.type === 'folder') {
126
    //             return {
127
    //                 name: node.name,
128
    //                 type: 'folder',
129
    //                 children: toArray(node.children)
130
    //             } as DirectoryNode;
131
    //         }
132
    //         return {
133
    //             name: node.name,
134
    //             type: 'file',
135
    //             url: node.url
136
    //         } as DirectoryNode;
137
    //     });
138

139
    //     // 排序逻辑：文件夹在前，文件在后，均按名称字母顺序
140
    //     arr.sort((a, b) => {
141
    //         if (a.type !== b.type) {
142
    //             return a.type === 'folder' ? -1 : 1;
143
    //         }
144
    //         return a.name.localeCompare(b.name);
145
    //     });
146

147
    //     return arr;
148
    // }
149
    function toArray(obj: Record<string, any>): DirectoryNode[] {
150
        // 👇 1. 在这里定义你想要的绝对顺序！（可以随意调整位置）
151
        const rootOrder = [
152
            rootMap.posts,    // 第 1 位：文章
153
            rootMap.notes,    // 第 2 位：随笔
154
            rootMap.diary,    // 第 3 位：日记
155
            rootMap.albums,   // 相册
156
            rootMap.projects, // 项目
157
            rootMap.skills,   // 技能
158
            rootMap.timeline  // 时间线
159
        ];
160

161
        const arr = Object.values(obj).map(node => {
162
            if (node.type === 'folder') {
163
                return {
164
                    name: node.name,
165
                    type: 'folder',
166
                    children: toArray(node.children)
167
                } as DirectoryNode;
168
            }
169
            return {
170
                name: node.name,
171
                type: 'file',
172
                url: node.url
173
            } as DirectoryNode;
174
        });
175

176
        // 👇 2. 核心修改：让排序逻辑优先听从你的安排
177
        arr.sort((a, b) => {
178
            // 规则1：文件夹永远排在文件前面
179
            if (a.type !== b.type) {
180
                return a.type === 'folder' ? -1 : 1;
181
            }
182

183
            // 检查这两个名字是否在我们的 VIP 顺序表里
184
            const indexA = rootOrder.indexOf(a.name);
185
            const indexB = rootOrder.indexOf(b.name);
186

187
            // 规则2：如果都在顺序表里，就严格按照表里的排名先后（重点）
188
            if (indexA !== -1 && indexB !== -1) {
189
                return indexA - indexB;
190
            }
191

192
            // 规则3：如果是其他普通的子文件夹/文件，还是按字母顺序自然排
193
            return a.name.localeCompare(b.name);
194
        });
195

196
        return arr;
197
    }
198
    return toArray(tree);
199
}

Ezorin