Mypage

本地用 Flutter 写 Hugo 博客，用 hugo-adapt 兼容多种主题 Front Matter，通过 Cloudflare Pages Direct Upload 上线。内容以 Markdown 为真相源，不依赖 Git 触发 Pages 构建。

架构一览

┌─────────────────┐     保存      ┌──────────────────────────┐
│  Flutter App    │ ────────────► │ pages/content/（源文件）   │
│  编辑器 + 预览   │               │ 多语言 posts、static 图片  │
└────────┬────────┘               └────────────┬─────────────┘
         │                                      │
         │ 预览 / 发布前                         │ hugo-adapt（Go）
         ▼                                      ▼
┌─────────────────┐               ┌──────────────────────────┐
│ hugo server     │ ◄── config ── │ pages/.hugo-build/content/ │
│ 内嵌 WebView    │     合并       │ 当前主题的 FM 方言         │
└─────────────────┘               └────────────┬─────────────┘
         │                                      │
         │ 正式发布                              │ hugo（构建 public/）
         ▼                                      ▼
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare Pages API（直传静态文件，无需 wrangler / Git CI）   │
└─────────────────────────────────────────────────────────────┘

要点：

• 只改 content/ 里的源稿；.hugo-build/ 是生成物，不要手改。
• 多语言站点通过 .hugo-build/hugo.content.toml 把各语言的 contentDir 指到适配目录（不能用全局 --contentDir）。
• 主题兼容靠 pages/adapters/*.yaml 注册表，不靠 pages/layouts/ 覆盖。详见 docs/THEME_COMPAT.md。

仓库目录

路径	说明
app/	Flutter 客户端（macOS 桌面为主：内嵌 Hugo 预览、站点设置、Cloudflare 发布）
pages/	Hugo 博客站点根（hugo.toml、content/、adapters/；主题与内容多在本地、已 gitignore）
hugobox/	HugoBlox Kit 独立站（go.mod、package.json、块编排落地页；见 docs/HUGOBOX.md）
App 落地页 模式	Flutter 拖拽编排 sections；见 docs/LANDING_EDITOR.md
tools/hugo-adapt/	按注册表转换 Front Matter 的 Go 工具
app/assets/hugo_adapters/	适配器模板；App 首次同步到站点 adapters/
scripts/	hugo-adapt / Hugo 构建 / 编译内置二进制的脚本
docs/	补充文档
hugo/	（可选，未入库）Hugo 源码克隆，供 scripts/build_hugo.sh 打出 App 内置 Extended 版

环境要求

组件	用途	说明
Flutter 3.8+	运行 App	cd app && flutter pub get && flutter run -d macos
Go 1.21+	运行 / 编译 hugo-adapt	或执行 ./scripts/build_hugo_adapt.sh 预编译到 app/third_party/
Hugo Extended	预览与构建	系统安装，或通过 scripts/build_hugo.sh 编译内置版

快速开始

1. 准备 Hugo 站点

开发时可直接用仓库里的 pages/：

# 在 pages/ 安装主题（示例，路径按你实际主题名调整）
cd pages/themes
git clone --depth=1 https://github.com/adityatelange/hugo-PaperMod hugo-PaperMod
git clone --depth=1 https://github.com/khusika/Reimu reimu

在 pages/hugo.toml 中设置 theme = "reimu" 或 "hugo-PaperMod" 等，与 pages/adapters/ 里注册的主题名一致。

App 里也可选择任意本地目录作为站点；默认会在用户目录创建 ~/MypageHugoSite 并写入脚手架文件。

2. 运行 App

cd app
flutter pub get
flutter run -d macos

1. 设置 → 选择 Hugo 站点目录（例如本仓库的 pages/ 绝对路径）。
2. 若提示缺少 Hugo：在设置中指定本机 hugo，或编译内置 Extended（见下文）。
3. 编辑文章 → 启动预览（自动全量 hugo-adapt + hugo server）。
4. 设置 → Cloudflare 登录 → 选择 Pages 项目 → 工具栏 正式发布。

发布失败时，完整日志会打在运行 flutter run 的终端（搜索 ========== 发布失败 ==========）。

3. 仅用命令行构建（可选）

./scripts/hugo_adapt.sh                    # 按 hugo.toml 的 theme 适配
./scripts/hugo_adapt.sh -theme hugo-PaperMod
./scripts/hugo_build.sh                   # 适配后 hugo build → pages/public/

不要单独执行 hugo 且不跑适配，否则 PaperMod 等主题可能因 cover 字段类型报错。

脚本说明

脚本	作用
scripts/hugo_adapt.sh	调用 Go 工具，生成 .hugo-build/content 与 hugo.content.toml
scripts/hugo_build.sh	先适配，再 hugo --config hugo.toml,.hugo-build/hugo.content.toml
scripts/build_hugo_adapt.sh	编译 hugo-adapt → app/third_party/hugo-adapt/bin/
scripts/build_hugo.sh	从相邻 hugo/ 源码编译 Extended → app/third_party/hugo/bin/

环境变量：

• SITE=/path/to/hugo/site — 覆盖默认的 pages/
• HUGO=/path/to/hugo — 覆盖 hugo 可执行文件

功能概览

• 多语言：content/zh-cn、content/en、content/ja、content/ko 等，由 hugo.toml [languages] 配置。
• Markdown 编辑：保存即写入源 content/；预览前防抖触发单篇 hugo-adapt -only。
• 主题切换：预览栏下拉选择已注册主题，写回 hugo.toml 并全量适配 + 重启 hugo server。
• 图片：插入后写入 static/images/，Markdown 使用站点路径。
• 发布：hugo 构建（不使用 --minify，避免 PaperMod JSON-LD 压缩失败）→ Cloudflare Pages Direct Upload。

主题与 Front Matter

推荐在文章中逐步统一为规范字段（适配器会从旧字段迁移）：

mypage:
  featured:
    image: /images/post/cover.jpg
    banner: /images/post/cover.jpg
    alt: ""

新增主题：在 pages/adapters/ 增加 YAML、安装主题到 pages/themes/、hugo.toml 的 theme 与适配器 match.themes 一致。细节见 docs/THEME_COMPAT.md。

Git 与本地数据

以下内容在 .gitignore 中，不会提交（每人本地一份）：

• pages/content/、pages/static/、pages/themes/、pages/i18n/
• pages/public/、pages/.hugo-build/、pages/resources/
• hugo/（Hugo 源码树）
• app/build/、.dart_tool/

适配器定义 pages/adapters/ 与 app/assets/hugo_adapters/ 会随仓库维护。

常见问题

预览 / 发布报 cover.image 或读的是 content/ 路径

• 确认已跑 hugo-adapt，且存在 pages/.hugo-build/hugo.content.toml。
• 勿在 1313 端口单独起未带双 config 的 hugo server；App 内用「重启 Hugo 预览」。

发布报 hugo-transform-error / JSON minify

• App 发布已去掉 --minify；若手动构建，也不要加 --minify。

找不到 hugo-adapt

./scripts/build_hugo_adapt.sh
# 或安装 Go 后由 App 自动 go run tools/hugo-adapt

可安全删除的本地缓存（会自动再生）

目录	说明
pages/public/	Hugo 构建输出
pages/.hugo-build/	适配结果
pages/resources/	Hugo 资源缓存
app/build/	Flutter 构建
hugo/	不需要编译内置 Hugo 时可删（体积大）

许可

本项目使用 Apache License 2.0（见 LICENSE），并提供 NOTICE 用于再分发时保留项目归属信息；第三方主题与 Hugo 遵循各自许可证。