结论： Butterfly 的高频改动应优先放在站点覆盖配置和 source 目录中，减少直接修改主题核心文件。
当前基线： Hexo 8.1.2、Butterfly 5.7.0；完整标签示例见《Markdown 与 Butterfly 写作速查手册》。

配置原则

本站的主题覆盖配置位于根目录 _config.butterfly.yml。菜单、搜索、侧栏、图片和评论等常规功能应优先在这里调整。

自定义样式和脚本分别放在主题的 source/css、source/js 中。修改主题模板前应先确认配置和 CSS 能否解决，避免后续升级产生大面积冲突。

文章置顶

在文章 Front Matter 中添加：

1
sticky: 2

数字越大，置顶优先级越高。只有真正承担入口作用的核心文章才需要置顶，历史教程不应长期占据首页顶部。

创建自定义页面

在 source 下建立页面目录，例如 source/example/index.md：

1
2
3
4
5
---
title: 示例页面
layout: page
comments: false
---

如果页面完全由独立 HTML、CSS 和 JavaScript 构成，可以使用：

1
2
3
---
layout: false
---

独立页面仍应检查移动端宽度、资源路径以及导航返回入口。

本地搜索

本站使用 Butterfly 5.7 的本地搜索配置：

1
2
3
4
5
search:
  use: local_search
  placeholder: 搜索文章
  local_search:
    preload: true

修改配置后执行 npx hexo generate，确认 public/search.xml 和搜索脚本正常生成。

插入原始 HTML

需要阻止 Markdown 渲染器处理局部 HTML 或模板代码时，可以使用 Raw 标签：

1
2
3
{% raw %}
<div class="example">HTML 内容</div>
{% endraw %}

不要在文章中直接嵌入来源不明的脚本。视频等第三方内容应使用 HTTPS，并补充标题与加载失败提示。

404 页面

主题配置中的 error_404.enable 控制 404 页面。修改后直接访问 /404.html 验证，不需要故意输入可能命中其他路由的地址。

发布前验证

1
2
npx hexo generate
npx hexo server

至少检查首页、文章页、自定义页面、搜索、移动端导航和浏览器控制台。日常热更新无需执行 hexo clean；只有删除页面后仍残留旧产物时才进行完整清理。