跳转至

Banner 生成工具

功能概览

scripts/content/generate-banner.js 是站点的统一横幅生成脚本，可批量读取 Hugo 内容的 front matter，按照 scripts/content/banner_presets.yaml 中的样式定义生成 WebP（或 JPEG 等）封面。脚本内置标签徽章、分类徽章、自动换行及字号自适应等逻辑，用于同时满足博客、图书章节、AI 资源等多种内容类型的封面需求。

默认仅处理各目录下的 index.md（及启用 --include-sections 时的 _index.md），并把生成的 banner.webp 写入对应目录，方便内容作者直接引用。通过 Front Matter 扩展的 “🎨 Generate Banner” 按钮调用时，会自动针对当前文件所在目录生成横幅。

前置条件

  • Node.js 20 或更高版本。
  • 安装依赖：npm install（项目根目录）。
  • 确保本地已安装脚本引用的字体（默认使用 NotoSansCJK 系列）。
  • 运行命令的工作目录为仓库根目录。

快速开始

# 在指定目录生成横幅（banner.webp 输出到内容目录内）
node scripts/content/generate-banner.js \
  --source content/zh/blog/fabric-cli-ai-pipeline/

常用参数说明：

  • --source：待扫描的内容目录，默认 content。
  • --output：导出目录，默认 static/images/generated-banners。（仅在 --no-inline-output 时生效。）
  • --config：自定义配置文件，默认 scripts/content/banner_presets.yaml。
  • --language：仅生成指定语言（zh/en），默认为全部。
  • --types：按内容类型过滤，例如 --types blog book。
  • --categories：按分类过滤，例如 --categories AI 工程实践。
  • --include-drafts：包含草稿内容。
  • --include-sections：处理 _index.md。
  • --skip-existing：若输出文件已存在则跳过。
  • --debug / 环境变量 BANNER_DEBUG=1：输出调试信息便于定位布局问题。

样式配置结构

横幅样式定义在 scripts/content/banner_presets.yaml，配置自上而下依次为：

defaults

  • fonts：标题、副标题字体路径与字号。
  • layout：通用布局（见下文）。
  • background：默认背景渐变或底图。
  • accents：可选的辅助形状（圆、带等）。
  • outputs：输出尺寸、格式、质量、缩放。
  • watermark：右下角水印。
  • subtitle：副标题来源，可设置 none 关闭。

styles

为内容类型预设样式，例如 blog、book、ai 等。常见字段：

  • layout.anchor：left/center/right。
  • layout.block_width_ratio：文字区域宽度相对画布比例。
  • layout.padding：顶部/右/底/左内边距（数组）。
  • layout.line_spacing：标题行距。
  • layout.badge：分类徽章偏移、间距、圆角。
  • layout.tags：标签徽章样式（间距、背景、字体等）。
  • background、accents：覆盖默认背景。

categories

分类可覆盖默认样式或引用已有 style：

categories:
  工程实践:
    layout:
      anchor: center
      block_width_ratio: 0.82
      padding: [ 120, 140, 160, 140 ]
      badge:
        spacing_after: 120
    tags:
      spacing_above: 70

这样即可针对特定分类（如“工程实践”）调节标题高度、徽章间距等参数。若需要引用样式，只需加入 style: ai 等键值后再补充差异化配置。

字体与排版要点

  • 脚本会根据 layout.max_title_chars 与内容长度自动截断（超出时尾部使用 …）。
  • 标题字号支持自适应缩放：当高度溢出时会按 layout.title_shrink_step 递减。
  • 标签徽章默认使用 meta.tags，脚本会去重并支持 prefix 添加 #。
  • 分类徽章文本来源为 front matter categories 第一项或 meta.banner.badge。

调试技巧

  • BANNER_DEBUG=1 或 --debug 可输出高度、行距、可用空间等信息。
  • 若标题背景覆盖分类徽章，可增大 layout.badge.spacing_after 或调高 layout.padding[0]。
  • 标签过多时可通过 layout.tags.max_lines 限制行数，或提高 spacing_above 增加顶部留白。

常见问题

问题 解决方法
生成的图重复显示标签 确认 subtitle.source 未设置为 tags_hashtags，并保留 layout.tags.enabled: true。
分类徽章被背景遮挡 调整 layout.badge.spacing_after 或分类覆盖中的 padding。
标题不居中 检查 layout.anchor 是否为 center，并在对应分类中保持相同设置。
输出尺寸不合适 修改 outputs 数组，设置 size 与 render_scale。

参考

  • 样式定义：scripts/content/banner_presets.yaml
  • 横幅脚本：scripts/content/generate-banner.js
  • 示例命令见 README 或上文“快速开始”章节
  • --inline-output / --no-inline-output：是否将生成文件保存在每个 index.md 所在目录（默认开启）。