本机写作到云端发布的完整闭环：编辑体验补强，发布链路重构

Hugo Markdown Client（简称 HMDC）使用方法

适用于 publish 文件夹中构建好的 HMDC.exe（单文件自包含版本）。本教程面向不熟悉命令行 / Git 的 Hugo 博客写作者，教你在图形界面里完成「写文章 → 本地预览 → 发布上线」的全部流程。

认识 HMDC
安装与启动
准备 Hugo（只需一次）
界面布局总览
第一步：打开 Hugo 项目
写文章：Markdown 编辑器详解
Frontmatter：文章元数据
编辑/预览模式切换
文件管理（新建/复制/重命名/删除）
本地预览：启动 Hugo 服务器
AI 助手（DeepSeek 加持）
构建发布到宝塔服务器
多语言网站：镜像复制
个性化：主题与语言
配置文件位置
常见问题排查

一、认识 HMDC

HMDC 是一款 Windows 桌面应用，目标是让完全不会命令行的用户也能管理 Hugo 静态博客。它把三大能力集成在一个窗口里：

写作：带格式工具栏、行号、表格/代码等一键插入的 Markdown 编辑器；
预览：一键在「源码」和「渲染后页面」之间切换；
发布：本地构建 public/ 后通过 SFTP 直接上传到宝塔服务器。

二、安装与启动

2.1 系统要求

Windows 10 / 11（64 位）
无需安装 .NET（HMDC.exe 是 self-contained 单文件，已内置运行时）
无需预装 Hugo（见下一节，可在 HMDC 内自动下载）
硬盘空间：程序本体约 76 MB

2.2 启动

把整个 publish 文件夹复制到任意位置（如桌面、D 盘），双击 HMDC.exe 即可运行。

提示：如果桌面快捷方式无效，或想固定到任务栏，直接用资源管理器在 HMDC.exe 上「发送到 → 桌面快捷方式」。

2.3 首次打开的界面

启动后你会看到：

顶部：工具栏（打开项目 / 保存 / 新建……）
左侧：「内容」文件树（空白）
中间：编辑器
右下：日志区
右上角：一个 AI 小按钮（默认折叠的 AI 助手，稍后用到）

先点**「打开 Hugo 项目」**，或按下一节先把 Hugo 准备好。

三、准备 Hugo（只需一次）

HMDC 需要用 Hugo 来「渲染预览」和「构建发布」。它会按下面顺序自动查找 hugo.exe：

工程师手动指定的路径（在设置里选过一次后永久记住）；
应用目录内嵌版（如果构建时嵌入了；
便携模式：HMDC.exe 同目录下的 hugo.exe，或 vendor\hugo\hugo.exe；
系统 PATH 中已有的 Hugo。

如果以上都没有，在你第一次点「▶ 启动 Hugo」或「构建发布」时，会弹窗让你三选一：

选项	含义
是	手动选择 hugo.exe 位置（适合你已经下载过 Hugo）
否	自动下载 Hugo（约 50 MB，带实时进度条，最省事）
取消	跳过本次，以后再配

推荐做法：选「否」让程序自动下载最新的 Hugo extended 版（支持 Sass/SCSS，兼容绝大多数现代主题）。下载完成后路径会被自动记住，之后不用再管。

💡 进阶：如果你希望「绿色便携」，也可以直接把 hugo.exe 放到 HMDC.exe 同目录，程序会优先用同目录版本。

四、界面布局总览

┌──────────────────────────────────────────────────────────────────────┐
│ 工具栏：打开项目│保存│另存为│新建文件│新建文件夹│重命名│删除 │▍▶启动Hugo│■停止 │构建发布│镜像 │        🌙 EN     状态栏 │
├───────────────────────────┬──────────────────────────────────────────┤
│ 文件树（内容）             │  编辑器标题栏：文件名          [AI] [👁]    │
│ ├─ 项目名                 │  ┌─ 行号 ┬─ Markdown 编辑区 ───────────┐ │
│ │  ├─ content             │  │ 1    │                            │ │
│ │  │   ├─ posts           │  │ 2    │                            │ │
│ │  │   │   ├─ 文章.md     │  │ 3    │   （或：图片预览 /          │ │
│ │  │   │   └─ ...         │  │ ...  │    渲染预览）               │ │
│ │  ├─ static              │  └──────┴────────────────────────────┘ │
│ │  └─ assets              │                                          │
│ ├── 新建/重命名/删除按钮   │                                          │
│ └── （右键有更多操作）     │                                          │
├───────────────────────────┴──────────────────────────────────────────┤
│ 日志区（Hugo 输出、发布进度、AI 操作记录）                            │
└──────────────────────────────────────────────────────────────────────┘

要点：

文件树右侧可以直接点文件打开；上传/发布类操作的状态都会实时显示在底部日志区；

五、第一步：打开 Hugo 项目

点击工具栏最左侧的 「打开 Hugo 项目」；
在弹出的文件夹选择框中，选中你的 Hugo 站点根目录（即包含 content/、themes/、config 等文件的文件夹）→「选择文件夹」。

打开后：

左侧文件树自动列出项目里的 content（文章内容）、static（静态资源）、assets（可处理资源）三个核心目录；
其他技术性目录（如 themes、public、.git、node_modules）会被智能隐藏，只留下你需要打交道的部分。

六、写文章：Markdown 编辑器详解

在文件树里双击/单击一个 .md 文件即可在中间打开编辑。编辑器是纯文本 Markdown 源码视图，但提供了很多贴心辅助：

6.1 格式化工具栏

打开文件后，编辑器上方出现一排格式按钮，选中文字后点按钮即可快速包上 Markdown 语法：

按钮	作用
B / I / S̶	加粗 / 斜体 / 删除线
H1 / H2 / H3	一级 / 二级 / 三级标题
🔗 / 🖼	插入链接 / 插入图片（`.md` 语法）
❝	引用块
`</>`	代码块（会自动把一个 \n ``` \n\n ``` \n 放进去，光标停在中间）
• / 1.	无序列表 / 有序列表
—	水平分割线
▦	插入一张三行三列表格（中英文自动适配）
⚙ Frontmatter	打开 Frontmatter 表单编辑器（见下节）

6.2 行号与自动换行

左侧灰色数字栏是行号，随编辑实时更新；
长行会自动折行显示（不用横向滚动）。

6.3 保存

Ctrl+S 快速保存已打开文件；
「另存为」可把当前内容存成新文件；
关闭/切换文件时如有未保存修改会自动提示保存。

6.4 新建文章

在文件树中选中要建在哪个文件夹（例如 content\posts）；
点工具栏 「新建文件」，输入文件名（自动补 .md），确定；
若该文件夹（或其上级）存在 _template.md 模板，新文件会自动套用模板；否则自动生成带 frontmatter 的空文章；
新文件创建后会自动打开，并自动弹出 Frontmatter 编辑器方便你填标题等信息。

文件夹模板：右键任意文件夹 →「新建模板」，会生成一个 _template.md。之后在该文件夹内新建文件都会以它为起点，非常适合统一文章的开头结构。

七、Frontmatter：文章元数据

Hugo 文章顶部那段 --- ... --- 之间叫做 Frontmatter，存放标题、日期、标签等元数据。HMDC 不让你手写 YAML，而是提供表单：

打开一篇 .md 文件，点格式工具栏的 「⚙ Frontmatter」；
弹出表单，可看到 title / date / draft / tags / categories / description 等字段（已有内容自动带入）；
预设下拉框：可选「基础」「文章」「完整」等内置预设，或你自己保存过的预设，一键填充默认字段；
可**「添加字段/删除字段」**自定义键值，支持 {{date}} 占位符（保存时自动替换为当前时间）；
点确定，程序自动生成规范 YAML 并写回文件顶部。

八、编辑/预览模式切换

编辑器右上角有一个 👁 图标按钮，可以在两种模式间切换（类似 VS Code / VNote）：

👁 预览：把当前 Markdown 渲染成页面显示（标题、列表、表格、代码块、链接都有样式），文章长什么样一眼看清；
点击后按钮变为 ✎ 编辑，点击即回到源码编辑。

细节：

预览时会自动隐藏 frontmatter，只渲染正文部分；
预览打开时格式化工具栏自动禁用（避免误改），切回编辑后恢复；
图片文件（.png/.jpg 等）会自动进入图片预览模式而不是 Markdown 预览。

小技巧：写完一段→点 👁 看效果→点 ✎ 继续改，配合 Ctrl+S 非常流畅。

九、文件管理

文件树支持类似「文件资源管理器」的完整操作：

9.1 工具栏按钮

选中文件/文件夹后，顶部按钮可：新建文件、新建文件夹、重命名、删除（删除有二次确认）。

9.2 右键菜单

在文件树任意位置右键，会展开完整菜单：

菜单项	说明
新建文件 / 新建文件夹	在当前选中目录下创建
重命名	改名（也可按 F2）
删除	删除选中项（有确认）
复制 / 粘贴	复制选中的文件或文件夹，再粘贴到目标位置（见下）
新建模板	生成 `_template.md` 文件夹模板
在文件资源管理器显示	用系统资源管理器打开该文件/文件夹

9.3 复制 / 粘贴（快捷键 Ctrl+C / Ctrl+V）

在文件树选中文件或文件夹，按 Ctrl+C（或右键复制）；
选中目标文件夹（或文件所在位置），按 Ctrl+V（或右键粘贴）；
同名冲突时自动变成 文件名 - 2.md、- 3.md…，不会覆盖原文件；
文件夹会整棵递归复制。

注意：这里的 Ctrl+C/V 只作用于文件树里的文件，不影响你在编辑器里复制文本；两者互不干扰。

9.4 其他快捷键

F2：重命名选中项
Esc：取消正在进行的重命名/新建对话框
新建/重命名/删除后文件树会保持展开状态，不会折叠。

9.5 刷新

十、本地预览：启动 Hugo 服务器

在发表之前，建议先在本地把整站跑起来看看效果。

确保已打开项目、且 Hugo 已就绪（见第三节）；
点工具栏 「▶ 启动 Hugo」；
底部日志区会实时滚动 Hugo 的输出（黄色字体状态行），看到 Web Server is available at http://localhost:1313 字样后：
- 浏览器会自动打开你的博客首页；
停止时点 「■ 停止 Hugo」。

注意事项：

服务器运行期间，你修改并保存 Markdown 后，刷新浏览器即可看到最新内容（Hugo 默认增量渲染）；
若提示「端口 1313 已被占用」，说明有别的 Hugo 进程在跑，先停掉再启动；
日志区可以拖动上方分隔条调整高度，也可以点「清空」按钮清屏。

Hugo 服务器模式下仅用于预览；真正的「发布」请看第十二节。

十一、AI 助手（DeepSeek 加持）

编辑器右上角有一个小小的 AI 按钮，点击展开 AI 面板——这是一个内置的 DeepSeek 大模型助手，能理解你的 Hugo 项目并帮你写作。

11.1 首次配置

点开 AI 面板（右上角 AI 按钮）；
点面板右上角的 ⚙（API 设置）；
填入：
- API Key：在 DeepSeek 开放平台注册获取
- Base URL：默认 https://api.deepseek.com 即可
- 模型：deepseek-chat（通用对话）或 deepseek-reasoner（深度推理）
点「测试连接」确认成功 → 保存。

11.2 使用方法

在底部输入框打字，Enter 发送，Shift+Enter 换行；
回复是流式的（逐字显示，像打字机），可在中途点「■」停止生成；
所有消息都能复制：直接鼠标选中，或点消息下方「⧉ 复制」。

11.3 与项目联动的能力

功能	操作
分析当前文件	输入框上方「分析当前文件」按钮 → 把当前打开的文章发给 AI，让它总结、提建议
分析项目结构	「分析项目结构」→ AI 会看到你的 content/static/assets 目录树，给出整站优化建议
读文件	让 AI「读取 content/posts/xxx.md」→ 它可自动访问项目文件后回答
让 AI 写文章	直接说“帮我写一篇关于 XXX 的 posts 文章”→ 它会把 `.md` 自动创建到 `content/`，并出现在文件树中
插入编辑器	对回复点「⤓ 插入编辑器」→ 内容插入到当前文章光标处
重新生成	点回复底部「↻」→ AI 重新回答

十二、构建发布到宝塔服务器

这是 HMDC 最核心的能力：本地一键把文章发布上线。流程是「用 Hugo 构建出 public/ → 通过 SFTP 上传到服务器站点目录」。全程不需要 Git、不需要命令行。

12.1 一次性的服务器配置

在宝塔面板确认：
- SSH 服务已开启（默认端口 22，可在宝塔「安全」查看/放行）；
- 你的站点目录路径（例如 /www/wwwroot/blog），并确认登录账号对它有写权限（常用 root，或用新建的 FTP/SFTP 专用账号）。
回到 HMDC，点击工具栏 「构建发布」；

首次会弹出发布设置对话框，填写：

字段	说明
服务器地址	服务器 IP 或域名，如 `120.25.235.17`
SSH 端口	默认 `22`
用户名	如 `root`（或 SFTP 专用用户）
密码	登录密码（推荐同时配置下方私钥，更安全）
OpenSSH 私钥文件	可选。点「浏览…」选 `.ssh\id_ed25519` / `.ssh\id_rsa`；有公钥则无需密码
远程站点目录	站点根目录，如 `/www/wwwroot/blog`

点 「测试连接」 确认「连接成功」→ 点「保存」。

之后想修改配置：在 「构建发布」按钮上点右键 →「⚙ 发布设置」 即可随时打开。

12.2 正式发布

每次写好文章后：

Ctrl+S 保存当前文件（程序也会自动保存未存内容）；
点 「构建发布」；
观察底部日志：
- Hugo building site (public/)... → Hugo 构建中，会逐行显示构建输出；
- 正在上传 ... → 用户@服务器:站点目录 → 正在通过 SFTP 上传；
- 每个上传的文件前有 ↑ 标记；
- 完成弹窗：「发布完成！上传 N 个，跳过未变化 M 个。」
浏览器打开你的站点地址，刷新即可看到更新。

12.3 增量上传（聪明且省流量）

程序会为每个文件记录 SHA256 哈希 + 大小（存在本机 %APPDATA%\HMDC\deploy-cache）；
下次发布时内容没变的文件直接跳过（即使 Hugo 重新生成了它们）；
所以只改一篇文章，通常只会传 1~2 个 HTML 文件，极快；
日志里的「跳过未变化 M 个」就是被跳过的数量。

想强制全量重传（例如服务器文件损坏想整体覆盖）：先删除本地的 %APPDATA%\HMDC\deploy-cache 文件夹，再点构建发布即可。

12.4 安全与注意事项

上传不会删除服务器上的文件：如果旧文件在服务器上但本地已删除，它的副本会留在服务器（防止误删你自己放的东西）。如确实需要清理，请到宝塔文件管理手动处理；
SFTP 账号只需站点目录的写权限即可，无需设置全盘权限；
密码会保存在本机 settings.json，建议尽量用私钥认证（更安全）。

12.5 常见失败排查

现象	处理
测试连接报「无法连接」	检查服务器 IP/端口是否可通、SSH 是否开启、安全组/防火墙是否放行 22
报「远程目录不存在」	在宝塔里先创建站点目录，或在发布设置里改对路径
报“CryptoAbstraction…exception”	旧版程序缺少 BouncyCastle 依赖，请用新版 HMDC.exe 重新发布
构建失败（Hugo 报错）	看底部日志的 Hugo 输出，通常是模板/文章语法问题

十三、多语言网站：镜像复制

如果你的站点是多语言版（例如 content/en/ + content/zh/ 并存的 Hugo 多语言模式），HMDC 可以把一篇文章复制到其他语言目录，保持相对路径一致：

打开一篇写好的文章；
点工具栏 「镜像复制」；
弹出框选择目标语言文件夹（程序会自动检测 content 下的 en/zh/fr 等语言目录）；
确认后：文件被复制到目标语言目录（如果已存在同名文件会自动覆盖提示），并自动打开新文件，方便你接着翻译正文。

只翻译文章本身，frontmatter 也一并复制过去。非常适合做中英双语的博客。

十四、个性化：主题与语言

14.1 亮/暗主题

工具栏右上角 🌙 按钮一键切换深色/浅色主题（白天 🌙 表示当前亮色、可切暗色；夜间 ☀ 反之）；
默认跟随系统深浅模式启动；
主题全局生效：主界面、对话框、AI 面板全部同步变色；
标题栏也会跟随深色（Windows 10/11 沉浸式标题栏）。

14.2 中英文界面

工具栏右上角 EN 按钮（或切回中）一键切换界面语言；
所有按钮、菜单、提示即时切换，重启后也会记住当前语言的开关状态（由运行时逻辑决定）。

十五、配置文件位置

内容	位置
应用设置（DeepSeek API Key、SFTP 配置、AI 面板宽度、Frontmatter 预设）	`%APPDATA%\HMDC\settings.json`
发布增量缓存（SHA256 清单）	`%APPDATA%\HMDC\deploy-cache\`

换电脑后，把这两处（或整个 %APPDATA%\HMDC 文件夹）一起拷走，就能带上你的全部配置；
想重置全部设置：退出 HMDC，删除 %APPDATA%\HMDC 文件夹后重新启动。

%APPDATA% 通常是 C:\Users\你的用户名\AppData\Roaming。可在地址栏直接粘贴 %APPDATA%\HMDC 回车打开。

十六、常见问题排查

Q1：双击 HMDC.exe 没反应 / 闪退

确认是 Windows 10/11 64 位；
确认是从 publish 完整拷贝（只需 HMDC.exe 一个文件即可运行，但别只拷快捷方式）；
若之前运行过旧版，删除 %APPDATA%\HMDC 后重试；
查看 Windows 事件查看器中的应用日志获取具体错误。

Q2：点「启动 Hugo」提示没有 Hugo

按第三节方式让程序自动下载，或手动指定 hugo.exe 路径（选编译过的 hugo.exe），或把 hugo.exe 放到 HMDC.exe 同目录。

Q3：AI 不回消息 / 报 API 错误

确认已配置有效的 DeepSeek API Key（开放平台申请）；
确认模型名正确（deepseek-chat）；
网络无法访问 api.deepseek.com 时请调整网络环境；
查看底部日志里的具体错误信息。

Q4：构建发布报「not a git repository」

新版本已不再依赖 Git，发布走 SFTP，此提示不应再出现；
若还出现，确认你用的是新版 HMDC.exe。

Q5：传上去网站没变化

确认远程站点目录填的是服务器 Nginx 实际读取的目录（宝塔→网站→设置→网站目录）；
发布完成后浏览器强制刷新（Ctrl+F5）清理缓存；
若服务器另有 CDN/宝塔缓存插件，记得刷新缓存。

Q6：发布很慢或卡住

首次会全量上传，耐心等待；
后续是增量，若还慢，检查本机→服务器网络质量；
大文件（视频/图片较多）时可以考虑压缩后再放进项目。

Q7：日志被大量 Hugo 输出刷屏

Hugo 构建/服务器日志会实时显示，可拖动分隔条或点「清空」按钮；下载 Hugo 的进度条是「就地更新」不会刷屏。

祝你写作愉快！有任何问题欢迎查阅本教程或查看底部日志中的详细提示。

Hugo Markdown Client 使用方法