> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.
# 页面布局契约
从 Halo 2.26.0 开始，主题可以通过 `templates/layout.html` 提供一个标准页面布局契约。插件提供的前台页面调用这个契约后，可以复用当前主题的页头、页脚、样式和响应式布局；如果当前主题没有适配，Halo 会使用内置的 fallback 布局保证页面可以继续渲染。
这个能力是增量适配项，不会影响主题安装、升级、启用，也不会替代主题内部自用的普通模板片段。
## 适配主题布局
主题需要在 `templates/layout.html` 中声明 `html(head, content)` 片段：
```html title="templates/layout.html"
```
其中：
- `head`：调用方提供的头部片段，通常用于插入页面标题、meta 信息或当前页面需要的资源。传入该片段时，调用方应提供最终的 ``；示例布局只在 `head` 为空时输出站点标题，避免同一页面出现两个标题。
- `content`：调用方提供的正文片段，应被插入到主题页面主体中。
主题可以自行决定外层容器、页头、页脚、暗黑模式、响应式布局等实现细节。建议保留 `<halo:footer />`，以便 Halo 和插件继续向页面底部注入必要内容。
如果你的主题已经使用 `templates/layout.html` 作为内部公共模板，只要它声明了 `html(head, content)` 片段，就可以同时作为页面布局契约使用。如果这只是主题内部私有模板，建议改用 `templates/modules/layout.html` 等其他路径，避免被识别为插件页面集成布局。
## 在主题页面中复用布局
主题自身的页面模板同样可以通过 `layout :: html(...)` 复用这个公共布局，不需要页头扩展时传 `head = null`：
```html title="templates/index.html"
<!DOCTYPE html>
<html
xmlns:th="https://www.thymeleaf.org"
th:replace="~{layout :: html(head = null, content = ~{::content})}"
>
<th:block th:fragment="content">
<!-- 文章列表 -->
<ul>
<li th:each="post : ${posts.items}">
<a
th:href="@{${post.status.permalink}}"
th:text="${post.spec.title}"
></a>
</li>
</ul>
</th:block>
</html>
```
放在 `templates/modules/layout.html` 等其他路径的私有布局，通过 `modules/layout :: ...` 引用。
## 插件页面调用布局
插件模板可以通过 `layout :: html(...)` 调用当前主题的页面布局：
```html title="src/main/resources/templates/moment.html"
<!DOCTYPE html>
<html
xmlns:th="https://www.thymeleaf.org"
th:replace="~{layout :: html(head = ~{::head}, content = ~{::content})}"
>
<th:block th:fragment="head">
<title>瞬间 - [[${site.title}]]