Maroon 架构文档

1
maroon/
2
├── packages/
3
│   └── astro-maroon/            # 独立主题包（可发布到 npm）
4
│       ├── src/
5
│       │   ├── components/      # UI 组件
6
│       │   │   ├── blog/        #   PostCard
7
│       │   │   ├── docs/        #   DocsSidebar
8
│       │   │   ├── home/        #   Hero, SeriesCard, SeriesSection
9
│       │   │   ├── shared/      #   Sidebar, TOC, PageNav
10
│       │   │   ├── Header.astro / Footer.astro / Search.astro
11
│       │   ├── layouts/
12
│       │   │   ├── BaseLayout.astro    # 根布局
13
│       │   │   ├── PostLayout.astro    # 博客文章
14
│       │   │   └── DocsLayout.astro    # 文档
15
│       │   ├── styles/          # CSS 变量、排版、布局
16
│       │   ├── types/           # SiteConfig, RoutesConfig, PostCardProps...
17
│       │   └── utils/           # formatDate, generatePath, themes...
18
│       └── package.json
19
│
20
├── src/                         # 主应用 — 胶水层
21
│   ├── config/
22
│   │   └── maroon.ts            # ⭐ 唯一配置入口（站点 + 内容类型 + 路由）
23
│   ├── content/
24
│   │   ├── blog/ / docs/ / pages/  # Markdown 内容
25
│   │   └── utils.ts             # 查询工具
26
│   ├── content.config.ts        # Zod Schema（Astro 强制路径）
27
│   ├── middleware.ts            # 配置注入 Astro.locals.site
28
│   └── pages/                   # 路由（极薄胶水层）
29
├── tsconfig.json                # 路径别名 → 主题包
30
├── astro.config.mjs
31
└── package.json                 # workspaces: ["packages/*"]

1
App 层 (src/)
2
  ├── config/maroon.ts ⭐   ──→  页面读取
3
  ├── content/blog/ docs/   ──→  pages/ 路由生成
4
  ├── middleware.ts          ──→  Astro.locals.site（运行时注入）
5
  └── pages/                ──→  调用主题包布局渲染
6

7
         ↓ Astro.locals.site + props
8

9
astro-maroon 主题包
10
  ├── layouts/
11
  │   ├── BaseLayout.astro     ← 根布局（Header + Footer + Search）
12
  │   ├── PostLayout.astro     ← 博客文章
13
  │   └── DocsLayout.astro     ← 文档页面
14
  ├── components/
15
  │   ├── shared/PageNav       ← 上下篇导航
16
  │   ├── shared/TOC           ← 目录
17
  │   ├── shared/Sidebar       ← 标签云 + 个人资料
18
  │   ├── blog/PostCard        ← 文章卡片
19
  │   └── docs/DocsSidebar     ← 文档分类侧边栏
20
  ├── styles/
21
  │   ├── base.css             ← CSS 变量 + 主题色
22
  │   ├── prose.css            ← 排版 + 代码块 + 表格
23
  │   └── layout.css           ← 网格 + 响应式断点
24
  └── utils/
25
      ├── content.ts           ← buildSidebarData, getTagStats
26
      ├── generate-path.ts     ← URL 路径生成
27
      ├── themes.ts            ← 主题列表
28
      └── toc-overlay.ts       ← TOC 浮层切换

1
// === 内容类型注册 ===
2
export const contentRegistry: ContentTypeConfig[] = [
3
  { id: 'blog', label: '博客', route: {...}, layout: 'post', ... },
4
  { id: 'docs', label: '文档', route: {...}, layout: 'doc', ... },
5
];
6

7
// === 站点信息 ===
8
export const siteConfig: SiteConfig = {
9
  title: '栗かな',  author: '栗かな',
10
  avatar: '/icon.png',  bio: '日语专业 / 技术探索中',
11
  social: { github: 'https://github.com/Mepuru' },
12
};

1
maroon.ts ──→ middleware.ts ──→ Astro.locals.site ──→ 所有布局/组件自动读取

1
context.locals.site = {
2
  ...siteConfig,       // 站点信息 + 导航
3
  themes,              // 主题列表
4
  defaultTheme,        // 默认主题
5
  routes: generateRoutes(),  // 路由表
6
};

1
props → Astro.locals.site → 硬编码兜底

1
{
2
  title, description, author, avatar, icon, bio,  // 站点信息
3
  nav: [{ href, label }],                          // 导航栏
4
  social: { github },                              // 社交链接
5
  footer: { icp, icpUrl },                         // 备案号
6
  docs: { emptyTexts },                            // 文档空状态
7
  themes: [{ id, name }],                          // 主题列表
8
  defaultTheme,                                    // 默认主题
9
  routes: { blog, docs, tags, about, home, icon }, // 路由表
10
}

1
.layout-wrapper.wide {
2
  display: block;
3
  /* max-width/padding 继承自 .layout-wrapper 基础规则 */
4
}

1
.layout-wrapper {
2
  display: grid;
3
  grid-template-columns: 1fr 260px;
4
  gap: 2rem;
5
  /* ↓ 博客页额外传给 BaseLayout: sidebar={true} */
6
}

1
.layout-wrapper.full-width {
2
  max-width: none;
3
  margin: 0;
4
  padding: 0 1.5rem;
5
}
6

7
.post-page {
8
  padding-left: 220px;       /* 给左侧 TOC 让位 */
9
}
10
.post-article {
11
  max-width: 800px;
12
  margin: 0 auto;
13
  padding: 2rem 1.5rem;
14
}

1
.docs-sidebar {
2
  position: fixed;
3
  left: 0;
4
  width: 260px;
5
}
6
.docs-main {
7
  margin-left: 260px;       /* 避开左侧侧边栏 */
8
  margin-right: 200px;      /* 避开右侧 TOC */
9
}
10
.doc-article {
11
  max-width: 800px;
12
  margin: 0 auto;
13
}
14
.toc-wrapper {
15
  position: fixed;
16
  right: 0.25rem;
17
  width: 200px;
18
}

1
---
2
// 1. Astro 内置
3
import { getCollection } from 'astro:content';
4
// 2. 主题包布局/组件
5
import BaseLayout from 'astro-maroon/layouts/BaseLayout.astro';
6
// 3. 本地工具
7
import { buildBlogSidebar } from '../../content/utils';
8
// 4. 类型
9
import type { PostCardProps } from 'astro-maroon/types';
10
// 5. 样式
11
import 'astro-maroon/styles/layout.css';
12
---

1
{
2
  id: 'notes',
3
  label: '笔记',
4
  route: { prefix: '/notes', pattern: '/notes/[slug]' },
5
  layout: 'post',
6
  sidebarIncluded: false,
7
  showInNav: true,
8
  hasTags: true,
9
  series: {
10
    description: '学习笔记',
11
    countLabel: '篇笔记',
12
    sortField: 'pubDate',
13
    sortOrder: 'desc',
14
  },
15
}

1
import { defineCollection, z } from 'astro:content';
2
import { glob } from 'astro/loaders';
3

4
const notes = defineCollection({
5
  loader: glob({ pattern: '**/*.md', base: './src/content/notes' }),
6
  schema: z.object({
7
    title: z.string(),
8
    pubDate: z.coerce.date(),
9
    draft: z.boolean().default(false),
10
  }),
11
});
12
export const collections = { blog, docs, pages, notes };

1
feat:     新功能
2
fix:      修复问题
3
refactor: 重构（不改功能）
4
docs:     文档更新
5
style:    代码格式清理（不影响逻辑）
6
chore:    构建配置/工具更新

1
<!-- ✅ 正确 -->
2
<a href={blogPrefix}>返回列表</a>
3
<!-- ❌ 错误 -->
4
<a href="{blogPrefix}">返回列表</a>

1
.prose table { display: block; max-width: 100%; overflow-x: auto; }