---
title: 三条规矩
desc: 路径决定 URL、元数据自述身份、index.astro 自由创作——目录的四种角色。
date: "2026-10-30"
order: 1
tags: [Astro, 框架设计]
---

## 三条规矩

给这个站立了三条规矩，多一条都嫌重：

1. **路径决定 URL**——目录层次就是地址层次，唯一的强约束；
2. **元数据自述身份**——目录的元数据写在 `atlas.json` 里，单文件的写在 frontmatter 里；
3. **index.astro 是自由创作**——页面读哪些数据、拼哪些积木，框架不管。

第一条管地址，第二条管数据，第三条管自由度。这个站后来所有机制，都是从这三句
推出来的。

## 目录的四种角色

目录在 `atlas.json` 里自报一种 `type`，和实际结构互验，写错了构建直接报错：

| type | 结构条件 | 用途 |
| --- | --- | --- |
| `map` | 有子目录或散篇 mdx | 索引页（如 `/posts/`） |
| `series` | 有 mdx 章节 | 文档树：落地页 + 目录树侧栏 |
| `section` | 住在系列树里且非空 | 分组节点：只当树用，不承载页面 |
| `case` | 叶子 | 内容本身（自由创作的页面） |

系列支持嵌套：`section` 分组里还能再放 `section`，像 doc 站那样把章节归组成树。
分组不需要 `index.astro`——建个目录、写份元数据（`title` + `order`）就上树。
章节和分组的 `order` 在同一层里混排，上一篇/下一篇沿整棵树深度优先走下来，
跨分组也是连续的。