Hugo 博客文章发布技能

本技能用于将 Markdown 文档和封面图发布到 Hugo 博客系统，支持 posts（博客文章）、daily（日报）、weekly（周报） 三种内容类型，可从任意目录执行发布操作。

核心功能

1. 1. 环境变量配置 - 通过环境变量配置博客路径，从任意位置执行
2. 查看分类目录 - 列出所有可用的博客分类
3. 发布文章 - 将 Markdown 文档复制到指定分类目录
4. 处理封面图 - 自动复制封面图并更新 front matter
5. 生成 front matter - 基于 Hugo 模板自动生成元数据
6. 草稿管理 - 支持将文章标记为草稿
7. 智能内容分析 - 自动检测数学公式、Mermaid 图表，自动添加 libraries
8. 分类/标签建议 - 根据内容智能建议分类和标签
9. Shortcodes 指南 - 内置 Shortcodes 使用参考

环境变量配置

配置方式

在 shell 配置文件中设置环境变量：

CODEBLOCK0

环境变量说明

路径优先级

命令行参数 > 环境变量 > 默认值

优先级逻辑：

1. 1. 命令行参数（如 --blog-dir）优先级最高
2. 环境变量（如 HUGO_BLOG_DIR）次之
3. 默认值优先级最低

使用方法

检查配置信息

CODEBLOCK1

输出示例：
CODEBLOCK2

查看 Shortcodes 使用指南

zzo 主题提供了丰富的 Shortcodes，用于增强文章表现力：

CODEBLOCK3

这将显示以下 Shortcodes 的快速参考：

• - 盒子（boxmd/box）- 支持 Markdown 的提示框
• 彩色提示框（alert）- info/warning/success/danger 四色警示
• 可折叠内容（expand）- 折叠长内容保持页面简洁
• 选项卡（tabs/codes）- 多平台/多语言内容对比
• 图片（img）- 带标题和说明的图片
• 按钮（button）- 行动号召按钮
• 封面图（featuredImage）- 显示 front matter 封面图

查看可用分类

posts 类型（需要指定分类）：
CODEBLOCK4

这将显示 content/zh/posts/ 下的所有分类目录：

• - AI
• AI编程
• 技术
• 思考
• 生活
• ...

daily/weekly 类型（直接查看现有文章）：
CODEBLOCK5

发布到 posts（博客文章）

需要指定 --category 参数，文章会放入对应子目录：

CODEBLOCK6

发布到 daily（日报）

无需指定分类，文章直接放入 content/zh/daily/：

CODEBLOCK7

发布到 weekly（周报）

无需指定分类，文章直接放入 content/zh/weekly/：

CODEBLOCK8

带封面图发布

CODEBLOCK9

封面图会被复制到文章所在目录，文件名格式为 {文章名}-cover.{扩展名}。

使用自定义目录（相对/绝对路径）

INLINECODE21 和 --template 参数支持相对路径和绝对路径：

CODEBLOCK10

发布为草稿

CODEBLOCK11

草稿文章的 draft 字段会被设置为 true，不会在博客中显示。

自定义文章名

CODEBLOCK12

自定义标签

CODEBLOCK13

智能内容分析

脚本会自动分析 Markdown 内容，智能添加以下功能：

1. 自动检测数学公式

如果内容包含 LaTeX 数学公式（$...$ 或 $$...$$），会自动在 front matter 中添加：
CODEBLOCK14

2. 自动检测 Mermaid 图表

如果内容包含 Mermaid 图表代码块（` `mermaid ），会自动在 front matter 中添加： CODEBLOCK15 ### 3. 自动检测图表内容 如果内容包含图表相关内容，会自动添加： CODEBLOCK16 ### 4. 智能分类建议 根据内容自动建议最适合的分类： - **技术**: 代码、编程、开发、架构、API、数据库、Docker、Git 等 - **AI**: AI、人工智能、机器学习、LLM、大模型、Claude、GPT、Prompt 等 - **生活**: 读书、电影、旅行、咖啡、美食、运动、日常、随笔等 - **思考**: 思考、观点、方法论、职业规划、成长、效率、复盘等 ### 5. 智能标签建议 根据内容自动建议相关标签： - **AI/LLM**: AI, Claude, GPT, LLM, Prompt, OpenAI, Anthropic, 大模型 - **编程**: Python, Java, Go, JavaScript, TypeScript, 架构, 微服务, 云原生 - **工具**: Obsidian, Docker, Git, Hugo, Cursor, VSCode - **效率**: 工作流, 自动化, 时间管理, 效率工具 - **生活**: 读书, 电影, 旅行, 咖啡, 健康 示例输出： CODEBLOCK17 ## Front Matter 处理 脚本会自动处理 Hugo 的 front matter： 1. **标题** - 使用文章名称或自定义名称 2. **日期** - 自动生成当前时间（格式：YYYY-MM-DDTHH:MM:SS+08:00） 3. **封面图** - 如果提供封面，自动填充 image 字段 4. **草稿状态** - 根据 --draft 参数设置 5. **Libraries** - 根据内容自动检测并添加（katex, mermaid, chart, flowchartjs） 6. **分类** - 智能建议或手动指定 7. **标签** - 智能建议或手动指定 ### 默认模板 **posts 类型**使用 archetypes/default.md： CODEBLOCK18 **daily 类型**使用 archetypes/daily.md（简洁版）： CODEBLOCK19 **weekly 类型**使用 archetypes/weekly.md： CODEBLOCK20 ## 工作流程建议 ### 推荐流程 1. **配置环境变量** CODEBLOCK21 2. **编写文章** - 在任意位置创建 Markdown 文件 - 使用 Obsidian 或其他编辑器 - 完成内容编写 3. **准备封面图（可选）** - 推荐尺寸：1200x630（社交媒体分享） - 支持格式：png, jpg, webp 4. **检查配置** CODEBLOCK22 5. **查看分类/现有文章** posts 类型（查看分类）： CODEBLOCK23 daily/weekly 类型（查看现有文章）： CODEBLOCK24 6. **发布文章** posts 类型（需指定分类）： CODEBLOCK25 daily 类型（直接发布）： CODEBLOCK26 weekly 类型（直接发布）： CODEBLOCK27 7. **本地预览** CODEBLOCK28 访问 http://localhost:1313 查看效果 8. **构建并部署** CODEBLOCK29 ## Shortcodes 使用参考 zzo 主题提供了丰富的 Shortcodes，用于增强文章表现力。 ### 盒子（Box） 支持 Markdown 语法的盒子： CODEBLOCK30 ### 彩色文本框（Alert） CODEBLOCK31 ### 展开栏（Expand） 可折叠的内容区域： CODEBLOCK32 ### 选项卡（Tabs） 代码选项卡（codes）： CODEBLOCK33java System.out.println("Hello World!"); CODEBLOCK34javascript console.log("Hello World!"); CODEBLOCK35 常规内容选项卡（tabs）： CODEBLOCK36 ### 图片（Image） CODEBLOCK37 显示 front matter 封面图： CODEBLOCK38 ### 按钮（Button） CODEBLOCK39 ### 使用建议 | Shortcode | 使用场景 | |-----------|----------| | boxmd / box | 提示框、注释框 | | codes / tabs | 多平台/多语言代码对比 | | expand | 折叠长内容，保持页面简洁 | | alert | 需要强调的四色警示信息 | | img | 需要标题和说明的图片 | | button | 行动号召按钮、链接跳转 | ## 文件命名规则 - 文章名会自动转换为小写 - 空格替换为连字符 - 移除特殊字符 - 示例："我的第一篇博客" → "我的第一篇博客" → "我的第一篇博客.md" ## 注意事项 1. **文章已存在** - 如果目标文件已存在，脚本会警告并覆盖 2. **原 front matter** - Markdown 文件原有的 front matter 会被移除 3. **分类不存在** - 如果指定的分类不存在，脚本会创建新目录 4. **封面图路径** - 支持相对路径和绝对路径 5. **博客验证** - 脚本会检查博客根目录是否包含 Hugo 配置文件 6. **路径处理** - --posts-dir 和 --template 参数支持相对路径和绝对路径。使用相对路径时，会自动相对于 --blog-dir 解析 7. **智能分析** - 脚本会自动检测数学公式（$...$、$$...$$）、Mermaid 图表（ `mermaid ），并添加相应的 libraries 8. **分类建议** - 当使用 --category 参数时，会覆盖智能分类建议 9. **标签建议** - 使用 --tags 参数指定的标签会与智能建议的标签合并，并自动去重 ## 完整参数说明 | 参数 | 简写 | 说明 | 默认值 | |------|------|------|--------| | --type | -t | 内容类型: posts/daily/weekly | posts | | --check-config | - | 显示当前配置信息和来源 | - | | --list-categories | -l | 显示所有分类目录（仅 posts 类型） | - | | --list | - | 显示现有文章（仅 daily/weekly 类型） | - | | --md | -m | Markdown 文件路径 | 必需 | | --cover | -c | 封面图片路径 | 可选 | | --category | -cat | 博客分类目录名称（posts 类型必需） | - | | --name | -n | 自定义文章名称 | 使用文件名 | | --draft | -d | 标记为草稿 | false | | --tags | - | 自定义标签（逗号分隔，例如：AI,Python,技术） | - | | --shortcodes | - | 显示 Shortcodes 使用指南 | - | | --blog-dir | - | Hugo 博客项目根目录（完整路径） | 环境变量或当前目录 | | --posts-dir | - | 目标目录完整路径。支持相对路径（相对于 blog_dir）或绝对路径 | 环境变量或默认相对路径 | | --template | - | 模板文件完整路径。支持相对路径（相对于 blog_dir）或绝对路径 | 环境变量或默认相对路径 | ## 技术细节 - **脚本语言**: Python 3 - **依赖**: 仅使用标准库 - **兼容性**: 支持 macOS/Linux/Windows - **编码**: UTF-8（支持中文） - **Hugo 验证**: 自动检测 config.toml/yaml/json - **智能分析**: 使用正则表达式检测数学公式、Mermaid 图表、图表内容 - **分类建议**: 基于关键词匹配的分类推荐算法 - **标签建议**: 基于内容的关键词提取和标签匹配 ## Resources ### scripts/ - publish_blog.py` - Hugo 博客文章发布脚本，实现所有核心功能

该脚本仅使用 Python 标准库，无需安装额外依赖。