从本地 Markdown 到 Notion：我的博客写作与发布流程

写作入口的变化

这个博客使用 Hexo 生成页面，通过 GitHub Pages 发布。最初的写作流程围绕本地文件展开：创建 Markdown 文件，准备图片，运行检查，提交 GitHub，再等待网站部署。

文章以外的内容也有各自的文件。动态保存在单独的目录，“关于”和“近况”分别对应固定页面。发布一条简短动态，同样需要处理文件和提交。

现在，文章、动态和页面文字统一在 Notion 中编辑。完成写作后，通过“发布状态”提交请求。程序负责生成文件、检查网站、提交内容、部署和核验。

这次转型保留 Hexo、现有主题和 GitHub Pages。网站仍然使用原来的生成和展示方式，日常写作改由 Notion 管理。

三类内容的管理

博客文章

“博客文章”管理长文章、教程和随笔。每篇文章包含标题、摘要、发布日期、分类、标签、封面和正文。

原有 13 篇文章已经导入 Notion。原文章地址继续保留，已有图片和封面继续使用。设置封面的文章在 Notion 页面顶部显示图片，没有封面的文章保持无封面。

文章列表保留日常需要查看的内容。封面、标签和摘要可以在文章页面中编辑。列表提供“全部文章”“写作进度”“待发布草稿”和“同步异常”四个视图。

博客动态

“博客动态”管理简短文字、照片、链接和音乐。已有 5 条动态导入后，继续保留原有日期、正文、照片和音乐。

动态标题用于查找和管理。网站显示正文、发布日期和附件。照片列表最多显示 9 张图片，分享链接和音乐可以与文字同时出现。

每条动态拥有固定链接。链接会打开动态列表，并定位到对应内容。修改正文或调整发布日期时，链接继续保留。

网站页面

“网站页面”管理“关于”“近况”和未找到页面的文字。各页面继续使用固定网址。正文通过 Notion 更新，页面布局和功能由网站程序控制。

分类页、标签页和动态列表由程序生成。日常需要编辑的文章、动态和页面文字，都有对应的 Notion 入口。

迁移已有内容

建立对应关系

迁移从现有网站内容开始。程序读取文章和动态的正文、日期与附件，创建对应 Notion 页面。固定页面按照已有用途导入。

每项内容保存 Notion 页面与仓库文件的对应关系。文章使用原有公开地址，动态保留文件标识，固定页面继续使用原有路径。

对应关系保存在两个记录文件中：

• notion/sync-state.json：文章记录。
• notion/content-state.json：动态和网站页面记录。

记录文件包含内容文件、公开地址、校验值和附件记录。后续修改根据这些信息找到原有内容，继续更新对应网站页面。

保存图片与附件

原有网站图片通过公开地址显示在 Notion 中。正文图片和文章封面继续使用已有图片，动态照片和音乐也保持原有内容。

在 Notion 上传的新图片，会下载到网站项目并保存为 WebP。上传附件保存为固定文件。网站使用保存后的地址，文件随内容一起提交 GitHub。

文章封面通过页面顶部设置。动态照片使用“照片”属性，分享封面和音乐封面分别使用对应属性。图片用途明确后，程序可以生成相应的网站内容。

在 Notion 发布文章

创建与写作

1. 打开“博客管理”，进入“博客文章”。
2. 点击“新建”，填写标题、摘要和发布日期。
3. 按需选择一个分类，添加标签。
4. 在页面正文中写作，插入图片、代码或公式。
5. 需要封面时，使用页面顶部的“添加封面”。
6. 写作期间将状态设置为“草稿”。

标题最多 200 个字符，摘要最多 2,000 个字符。文章正文需要包含有效内容。封面可以省略。

提交发布

检查正文和文章属性后，将状态改为“发布”。同步程序运行时读取内容，并生成网站文章。

状态变为“已发布”后，打开“文章链接”查看实际网站。已公开文章的发布日期需要保持原值，原有地址继续保留。

文章发布日期按北京时间判断。设置未来日期后，程序等待到指定日期之后的同步任务。

在 Notion 发布动态

文字与照片

1. 进入“博客动态”，点击“新建”。
2. 填写便于查找的标题，设置发布日期。
3. 在正文中输入文字。
4. 需要照片时，在“照片”属性中上传图片。
5. 按需填写地点和标签。
6. 将状态改为“发布”，等待“已发布”。
7. 打开“动态链接”，查看对应动态。

照片属性中的图片按顺序显示为照片列表。正文中插入的图片显示在正文中。两种位置可以按内容需要使用。

动态可以只包含照片，也可以只包含链接或音乐。照片文件名称可以用作图片说明。

网页与音乐

分享网页时，在“分享链接”中粘贴 HTTPS 地址。需要自定义卡片时，填写分享标题、分享说明和分享封面。

分享网易云音乐时，在“音乐链接”中粘贴歌曲地址。歌曲、歌手和音乐封面可以按需填写。需要发布上传的音频时，使用“音频”属性。

更多属性放在页面的属性侧栏中。作者和头像留空时，网站使用默认作者和头像。普通文字动态只需要关注正文、日期和发布状态。

动态可以设置日期和时间。程序按北京时间排序，未来时间的内容等待到指定时间之后的同步任务。

更新内容与继续写作

修改已发布内容

处于“已发布”状态的内容，后续编辑会自动同步。修改完成后，程序在下一次运行中读取新内容，发布并核验网站。

需要集中修改并完整检查时，编辑前选择“草稿”。网站保留此前公开的版本。写作完成后重新选择“发布”。

“关于”“近况”等页面也使用相同的更新方式。页面类型与固定地址保持原值，日常只编辑标题、摘要和正文。

下线与恢复

文章和动态支持“下线”。程序移除公开内容，保留 Notion 正文和仓库归档文件。网站核验通过后，状态变为“已下线”。

需要恢复时，重新选择“发布”。文章恢复原有地址，动态恢复原有固定链接。固定网站页面使用草稿和发布流程管理修改。

自动发布如何运行

读取与生成

GitHub Actions（自动任务）运行“Notion Sync”。任务计划每隔 30 分钟执行，也可以手动运行。计划任务可能延迟执行。

程序读取 Notion 内容，根据发布状态决定处理范围。草稿暂停公开更新，未来日期或时间的内容继续等待。

符合发布条件的内容转换为 Markdown。图片和附件保存到项目。转换结果写入原有文章文件、动态文件或固定页面文件。

检查与部署

程序检查文件、图片、文章地址和同步记录，然后使用 Hexo 构建网站。内容文件和记录一起提交 GitHub，网站由 GitHub Pages 部署。

部署完成后，程序读取实际网站，与本次构建结果比较。文章和固定页面核对页面内容。动态核对列表页面，并检查对应动态是否存在。

“已发布”表示网站核验已经通过。下线文章需要确认原地址返回未找到状态，下线动态需要确认对应内容已经移除。

修改期间的处理

同步程序在写入前再次读取 Notion 页面。内容在同步期间发生变化时，程序终止本次处理，等待重新运行。

回写状态前也会检查页面修改时间。发布期间再次编辑的内容保留当前状态，等待后续同步。程序根据最新页面继续处理。

保存位置与内容历史

Notion 与 GitHub

Notion 保存写作页面和草稿。GitHub 保存公开内容的 Markdown、图片、附件、同步记录和网站程序。

新草稿保存在 Notion。请求发布并成功同步后，仓库生成对应内容文件。电脑中的项目通过 git pull 取得这些文件。

电脑可以关闭。同步、构建和部署在 GitHub 运行。日常写作直接在 Notion 中完成。

本地维护

网站样式、功能和部署配置继续通过项目维护。内容统一在 Notion 编辑，生成文件用于构建网站和保存历史。

确实需要从本地更新内容时，读取最新文件并明确导入对应页面。例如：

npm run notion:import -- --file 'source/_moments/2026-07-16-blog-update.md' --replace
npm run notion:sync
npm run verify
npm run notion:check

--replace 将指定文件的内容上传到对应 Notion 页面。运行前需要核对页面与文件，确认需要保留的内容。

发布失败时的处理

“同步异常”显示需要处理的内容。出现“发布失败”或“下线失败”时，打开发布工作流，查看最早出现错误的步骤。

正文使用未支持的类型、附件超过限制、资源无法读取或内容文件与记录不同，都会使任务终止。每个上传附件最多 25 MB（兆字节）。

修正内容后，重新选择“发布”或“下线”。状态恢复正常前，保留正文和原始附件。网站在新的部署完成前继续保留此前公开的内容。

本次转型的交付

文章、动态和网站页面拥有对应的 Notion 管理入口。原有 13 篇文章、5 条动态和 3 个文字页面纳入同步管理，原有文章地址与页面网址继续保留。

管理页面提供日常写作、提交发布、更新内容、下线恢复和异常处理说明。仓库中的维护文档记录命令、文件位置和后续接入方式。

这篇文章也通过 Notion 提交发布。它对应一次实际的写作、内容转换、构建、部署和网站核验流程。