FlatPaper(v0.3.3) 文章、页面顶部图：top_img 与 post_top_img 配置

FlatPaper 现在支持文章页顶部图了。它和首页 Hero 不一样：顶部图只服务于单篇文章阅读页，会铺在文章纸面最上方，标题、分类和日期信息直接叠加在图片上，图片再以半透明渐变自然过渡回正文纸面。

这个功能适合用来给长文增加一点视觉识别度。比如教程类文章可以放配置截图，游记和摄影记录可以放照片，主题更新日志可以放功能预览图。它不会强迫所有文章都显示图片，也不会改变没有配置图片的文章。

全局配置

主题配置项是 post_top_img.mode。mode 留空时等于禁用。

1 2	post_top_img: mode:

需要启用时，可以在两种模式之间选择：

1 2	post_top_img: mode: top_img

top_img 模式只接收文章 front-matter 里显式写出的 top_img。如果某篇文章没有写 top_img，就不会渲染顶部图。

1 2	post_top_img: mode: fallback

fallback 模式会先读取文章 front-matter 的 top_img。如果没有配置 top_img，再回退到主题已有的封面图解析顺序：cover、thumbnail、image、banner，最后尝试正文第一张图片。

在文章 front-matter 中直接写 top_img：

---
title: 周末散步记录
date: 2026-06-26 15:30:00
cover: /images/walk-card.jpg
top_img: /images/walk-wide.jpg
---

top_img 可以是站内路径，也可以是完整 URL。站内图片建议放在 Hexo 的 source/images/ 目录下，然后用 /images/example.jpg 引用。

如果某篇文章不想显示顶部图，可以写：

---
title: 一篇保持普通纸面的文章
top_img: false
---

即使全局 mode 是 fallback，top_img: false 也会关闭当前文章的顶部图。

比如这个 DEMO 站点的 Cover 就都写了标题，其实不太适合直接 Fallback。

如果站点里的 cover 大多是横向封面，推荐使用 fallback。如果 cover 主要是小卡片图、图标图或不适合铺满文章顶部，推荐使用 top_img，只给适合的文章单独配置。

cover 主要用于首页文章卡片、精选卡片和相关文章卡片；top_img 只用于文章详情页顶部。

你可以让它们使用同一张图片：

1 2	cover: /images/post.jpg top_img: /images/post.jpg

也可以分开使用：

1 2	cover: /images/post-card.jpg top_img: /images/post-wide.jpg

第二种方式更适合视觉要求高的站点：卡片图可以裁得紧一点，文章顶部图则使用更宽、更安静、能承载标题文字的图片。

顶部图会保留 FlatPaper 的纸面感。图片不会直接硬切到正文，而是通过半透明遮罩和渐变融入文章背景。标题区域叠在图片上，但文字仍使用主题的墨色系统，并通过轻微的纸面色光晕保证可读。

顶部图片也被设置为不可拖动，避免阅读时不小心拖出浏览器的图片预览。

如果你想先在演示站或个人站里快速试用，可以从 fallback 开始：

1 2	post_top_img: mode: fallback

之后遇到不适合铺成顶部图的文章，再单篇关闭：

1	top_img: false

如果你更喜欢手动控制每一篇文章的视觉效果，就改用：

1 2	post_top_img: mode: top_img

这样只有认真配置过 top_img 的文章才会显示顶部图，站点整体会更克制。

在文章也支持了顶部图片后，其他类型页面也光速获得了支持。

但是其他页面只接收 top_image: 手动指定，毕竟页面部分不需要频繁更新，还是值得精挑细选准备一下的。

预览效果可以查看：