路由结构详解

URL 设计原则

• 所有页面 URL 以 .html 结尾（Astro build.format: 'file'）
• 使用小写连字符命名
• 栏目首页 URL 格式：/{section}.html
• 文章详情 URL 格式：/{section}/{subsection}/{slug}.html

页面路由对照表

动态路由机制

通用文章路由

[section]/[subsection]/[slug].astro 是核心通用路由，处理 cloud/network/os 等所有多层级栏目的文章。路由参数映射：

// 示例: /cloud/ansible/01-ansible-lab-setup.htmlparams: {section: 'cloud',           // sections.json 中的 section.idsubsection: 'ansible',      // sections.json 中 subsection.route 的最后一节slug: '01-ansible-lab-setup' // entry.id 去掉 .mdx 后缀}

手册独立路由

manuals/ 下的各手册使用独立的 [slug].astro 路由文件，与通用路由分离开，避免路由冲突。在通用路由的 getStaticPaths 中通过 section.id === 'manuals' 跳过。

技术文章路由

tech/[slug].astro 独立处理技术文章集合，同样在通用路由中通过 section.id === 'tech' 跳过。

路由优先级

Astro 按以下优先级匹配路由：

1. 精确路径（如 index.astro）
2. 动态参数路径（如 [slug].astro）
3. 多级动态参数（如 [section]/[subsection]/[slug].astro）
4. Rest 参数（如 [...slug].astro）

添加新栏目

新增栏目需要同步修改 3 处：

1. sections.json — 添加 section 和 subsection 条目，配置 articleConfig2. content.config.ts — 定义新集合并导出3. src/content/ 下创建对应目录和 MDX 文件

// content.config.ts 示例const newTopic = defineCollection({loader: glob({ pattern: "**/*.mdx", base: "./src/content/new-topic" }),schema: baseSchema,});export const collections = { 'new-topic': newTopic, ... };

路由将自动生成，无需手动创建路由文件（使用现有的通用路由）。