tomevault-io MDX 核心理念
本项目的核心是基于 MDX 的内容创作系统。为了保证内容在 SEO 和交互性之间的平衡，必须遵循以下处理原则。
1. 渲染策略 (SSR vs CSR)
- 页面级渲染 (SSR): 在
frontend/src/app/posts/[slug]/中，优先使用 Server Components 进行数据获取和初步渲染，以确保 SEO 友好。 - 组件级交互 (CSR): 涉及代码高亮、复制按钮、Mermaid 图表等交互元素时，使用
next-mdx-remote的客户端组件模式进行 Hydration。
2. 组件注册架构 (Registry Pattern)
代码路径：frontend/src/components/mdx/
- 注册层 (
registry/): 仅负责 HTML 标签到 React 组件的映射（如pre->CodeBlock）。严禁在此层编写业务逻辑。 - 实现层 (
components/): 处理具体逻辑。例如，CodeBlock组件应内部判断内容是否为mermaid语言并分发渲染逻辑。 - 添加新组件:
- 在
components/创建实现。 - 在
registry/mdx-components.tsx注册映射。
- 在
3. 内容同步与元数据 (Git Sync)
规范参考：GIT_SYNC_GUIDE.md
- Frontmatter: 必须包含
title,author,tags等核心字段。 - Slug 处理: 后端同步时会自动调用
generate_slug_with_random_suffix。在 MDX 文件中仅定义逻辑 Slug（如my-post），不要手动添加后缀。 - 图片路径: 在 MDX 中引用图片时，优先使用媒体库相对路径。
4. 特殊内容处理
- 数学公式: 使用 KaTeX 语法，确保前后端解析器一致。
- 流程图: 使用
mermaid语言块。 - 自定义交互: 使用注册好的自定义组件（如
<InteractiveButton />），避免在 MDX 中编写原生内联 script。
维护原则
- 修改渲染逻辑时，必须同时考虑 Dark/Light 模式的样式兼容。
- 保证 MDX 的输出 AST 结构稳定，避免前端解析崩溃。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.