02 项目结构与源码入口

页面入口

以下路径相对 module/。

目录或入口职责
layouts/baseof.html页面整体装配
layouts/page-*.html内容选择的页面布局
layouts/_partials/入口私有模板、功能模板与系统机制
layouts/_shortcodes/正文短代码
layouts/_markup/Markdown 渲染
layouts/rss.xml、sitemap.xml、home.llms.txt订阅与站点发现输出
assets/js/、assets/css/浏览器行为与样式

page-* 是布局命名,不表示 Hugo 的 page 类型。集合布局用于普通栏目;首页另支持汇总图片墙。当前没有 taxonomy 和 term 的列表布局。配置方法见列表与产品声明。

Partial 所有权

目录(相对 layouts/_partials/)职责
entry-baseof/、entry-page-home/入口独有的装配与检查
feature-browse/内容成员、引用、列表、图片墙和导航
feature-document/正文、元信息、章节与文章结构化数据
feature-preferences/语言和外观选项
feature-prefetch-debug/、feature-site-status/诊断与状态显示
system-ui/公共列表、图标、控件与页面样式
system-assets/资源定位、处理、构建与发布
system-metadata/SEO、分享信息和 Agent 索引
system-delivery/SW、预取、缓存与部署配置
system-build/站点构建版本与时间

依赖方向

入口组合功能与系统模块;功能模块可以使用系统模块,系统模块不反向读取功能状态。跨功能依赖保持明确、单向,例如文章元信息读取内容归属。

公共 UI 接收功能模块生成的字段与链接,不负责发现成员。资源构建接收调用者指定的资源,不自行读取浏览来源。SEO 消费构建期模型,不以浏览器来源作为规范路径。

新增代码先放在所属入口或功能附近,出现实际复用后再提取。不要为目录对称增加空层或转发模板。

功能内部边界

重要约定源码入口(相对 layouts/_partials/)
列表、计数、RSS 与反向引用共用成员索引feature-browse/directory/index.html
引用不创建页面,不改变 Parent 与正文网址feature-browse/directory/
结构路径与浏览来源分别维护feature-browse/navigation/
资源定位与发布分开,衍生图不必额外发布源图system-assets/resolve-page.html、publish-page.html
共享列表只装配公共控件system-ui/list/
内联脚本与 CSP 使用同一份最终正文entry-baseof/inline-scripts.html、system-delivery/deployment/csp-value.html

站点发现使用实际发布页面;引用不会产生新的规范地址。LLMS 可以把同一正文列入真实栏目和引用栏目,规则见站点发现。

导航模型见面包屑导航模型,网址状态见导航状态协议,组件与样式入口见UI 命名与职责。本地运行与检查入口见本地开发。

下一步

按改动范围从开发资料选择约定和检查。局部实现说明在对应源码附近。

横向滚动 · 单击或按 Esc 退出