update-blog-by-siyuan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sync-siyuan — 思源笔记同步到 Hexo 博客

sync-siyuan — Sync SiYuan Note to Hexo Blog

将思源笔记文档同步发布到 Hexo Butterfly 博客，包括正文转换和图片复制。

Sync and publish SiYuan Note documents to Hexo Butterfly blog, including content conversion and image copying.

Pre-check

思源 MCP 可用：
```
mcp__siyuan-mcp__unified_search
```
能正常调用
博客目录存在：
```
source/_posts/
```
可访问
图片目录存在：
```
source/post_imgs/
```
可访问
思源数据目录可访问：
```
D:/299792458/Q7h2q9/data/assets/
```

未满足时：提示用户检查思源是否运行、MCP 是否配置、路径是否正确。

SiYuan MCP is available:
```
mcp__siyuan-mcp__unified_search
```
can be called normally
Blog directory exists:
```
source/_posts/
```
is accessible
Image directory exists:
```
source/post_imgs/
```
is accessible
SiYuan data directory is accessible:
```
D:/299792458/Q7h2q9/data/assets/
```

If the above conditions are not met: Prompt the user to check whether SiYuan is running, MCP is configured, and the path is correct.

Usage

/sync-siyuan <文档标题>

参数：

$ARGUMENTS

— 思源文档标题（支持模糊匹配）

/sync-siyuan <document title>

Parameter:

$ARGUMENTS

— SiYuan document title (fuzzy matching supported)

关键路径

Key Paths

用途	路径
思源 assets	`D:/299792458/Q7h2q9/data/assets/`
博客文章目录	`D:/299792458/blog/butterfly/source/_posts/`
博客图片目录	`D:/299792458/blog/butterfly/source/post_imgs/`

Purpose	Path
SiYuan assets	`D:/299792458/Q7h2q9/data/assets/`
Blog post directory	`D:/299792458/blog/butterfly/source/_posts/`
Blog image directory	`D:/299792458/blog/butterfly/source/post_imgs/`

Workflow

1. 搜索思源文档

1. Search for SiYuan Documents

使用

mcp__siyuan-mcp__unified_search

：

```
filename
```
: "$ARGUMENTS"
```
types
```
:
```
["d"]
```

无结果 → 告知未找到，结束。多个结果 → 列出让用户选择。

Use

mcp__siyuan-mcp__unified_search

```
filename
```
: "$ARGUMENTS"
```
types
```
:
```
["d"]
```

No results → Inform the user that no matching document is found, end the process. Multiple results → List all results for the user to select.

2. 读取文档内容

2. Read Document Content

使用

mcp__siyuan-mcp__get_document_content

读取完整 Markdown。

Use

mcp__siyuan-mcp__get_document_content

to read the complete Markdown content.

3. 处理正文

3. Process Content

按顺序执行：

去掉一级标题（
```
# xxx
```
）— Hexo 用 frontmatter title
去掉思源 frontmatter（如果有）
清理零宽字符：
```
\u200b
```
、
```
\u200d
```
、
```
\u200c
```
、
```
\uFEFF
```
提取所有图片引用，收集图片文件名列表（用于步骤 4）
替换图片路径：
```
assets/xxx.png
```
→
```
post_imgs/xxx.png
```

图片引用格式示例：

思源原始：

![image](assets/image-20260305161734-22rhrm8.png)

转换后：

![image](post_imgs/image-20260305161734-22rhrm8.png)

Execute in order:

Remove the first-level heading (
```
# xxx
```
) — Hexo uses frontmatter title
Remove SiYuan frontmatter (if any)
Clean up zero-width characters:
```
\u200b
```
,
```
\u200d
```
,
```
\u200c
```
,
```
\uFEFF
```
Extract all image references, collect the list of image filenames (used in step 4)
Replace image path:
```
assets/xxx.png
```
→
```
post_imgs/xxx.png
```

Image reference format example:

Original SiYuan format:

![image](assets/image-20260305161734-22rhrm8.png)

Converted format:

![image](post_imgs/image-20260305161734-22rhrm8.png)

4. 复制图片

4. Copy Images

对步骤 3 收集的每个图片文件名：

bash

cp "D:/299792458/Q7h2q9/data/assets/<filename>" "D:/299792458/blog/butterfly/source/post_imgs/<filename>"

复制前检查源文件是否存在，不存在则警告用户（不中断流程）
目标已存在则跳过（避免重复复制）
批量复制，一条命令处理多个文件

For each image filename collected in step 3:

bash

cp "D:/299792458/Q7h2q9/data/assets/<filename>" "D:/299792458/blog/butterfly/source/post_imgs/<filename>"

Check if the source file exists before copying, warn the user if it does not exist (do not interrupt the process)
Skip if the target file already exists (to avoid duplicate copying)
Batch copy, process multiple files with one command

5. 检查博客是否已有该文章

5. Check for Existing Article in Blog

在

source/_posts/

下查找同名或相关 .md 文件。

Search for .md files with the same or related names under

source/_posts/

6. 生成/更新博客文章

6. Generate/Update Blog Article

新文章

New Article

生成 frontmatter：

yaml

---
title: <文档标题>
cover:
categories:
tags:
date: <当前时间 YYYY-MM-DD HH:mm:ss>
lastmod: <思源文档更新时间>
---

写入

source/_posts/<文档标题>.md

。提醒用户补充 cover、categories、tags。

Generate frontmatter:

yaml

---
title: <document title>
cover:
categories:
tags:
date: <current time YYYY-MM-DD HH:mm:ss>
lastmod: <SiYuan document update time>
---

Write to

source/_posts/<document title>.md

. Remind the user to fill in cover, categories and tags.

更新已有文章

Update Existing Article

保留原 frontmatter（title、cover、categories、tags、abbrlink、date）
只更新 lastmod
替换正文内容
新增图片同样复制

Keep the original frontmatter (title, cover, categories, tags, abbrlink, date)
Only update lastmod
Replace the body content
Copy newly added images as well

7. 部署（可选）

7. Deploy (Optional)

询问用户是否立即部署。如果是：

bash

cd D:/299792458/blog/butterfly && hexo clean && hexo g && hexo d

注意：部署会推送到 GitHub Pages，确认用户意图后再执行。

Ask the user whether to deploy immediately. If yes:

bash

cd D:/299792458/blog/butterfly && hexo clean && hexo g && hexo d

Note: Deployment will push to GitHub Pages, execute only after confirming the user's intention.

8. 完成

8. Complete

简要告知：

新建/更新
文件路径
复制了几张图片（如有缺失也列出）

Briefly inform the user of:

Created/Updated status
File path
Number of copied images (list missing images if any)

Error Handling

症状	原因	修复
MCP 工具调用失败	思源未运行或 MCP 未配置	启动思源笔记，检查 MCP 配置
图片源文件不存在	思源中已删除或文件名变更	警告用户，继续处理其余图片
frontmatter 解析异常	文档格式不标准	手动检查思源文档格式
hexo d 失败	Git 认证或网络问题	用户手动执行 `hexo d`

Symptom	Cause	Fix
MCP tool call failed	SiYuan is not running or MCP is not configured	Start SiYuan Note, check MCP configuration
Image source file does not exist	Deleted in SiYuan or filename changed	Warn the user, continue processing other images
Frontmatter parsing exception	Non-standard document format	Manually check SiYuan document format
`hexo d` failed	Git authentication or network issue	User manually executes `hexo d`

Notes

思源图片文件名格式：
```
image-YYYYMMDDHHmmss-随机ID.png
```
不要修改
```
themes/butterfly/
```
下的任何文件（submodule）
abbrlink 由 hexo-abbrlink 插件自动生成，新文章不需要手动填写
部署前建议
```
hexo s
```
本地预览确认

SiYuan image filename format:
```
image-YYYYMMDDHHmmss-random ID.png
```
Do not modify any files under
```
themes/butterfly/
```
(submodule)
abbrlink is automatically generated by the hexo-abbrlink plugin, no need to fill in manually for new articles
It is recommended to run
```
hexo s
```
for local preview and confirmation before deployment