Create Blog Post
Convert source content (markdown files, notes, documents) into Jekyll-formatted blog posts.
When to Use
- User wants to create a new blog post
- User wants to migrate/convert an existing article to their Jekyll blog
- User mentions "博客", "blog", "写博客", "发文章", "迁移文章"
Blog Configuration
Detect blog settings from the target repository:
- Find the blog repo: Look in sibling directories of the current project, or ask the user. Common patterns:
~/code/<username>.github.io/, ~/code/<username>.github.com/
- Posts directory:
_posts/ inside the blog root
- Naming convention:
YYYY-MM-DD-<slug>.md
- Existing categories/tags: Scan recent posts in
_posts/ to infer conventions
Frontmatter Format
Every blog post must start with this frontmatter:
---
layout: post
title: "<文章标题>"
description: "<一句话摘要，用于 SEO 和列表预览>"
category: "<分类>"
tags: ["<标签1>", "<标签2>", ...]
---
Rules
- title: Chinese, enclosed in double quotes. Concise and descriptive.
- description: Chinese, one sentence summarizing the article. Used for SEO meta description.
- category: Infer from the article topic. Check existing posts for consistency. Common values: "AI", "编程", "工具", "架构", etc.
- tags: Array of 2-5 relevant tags. Include the category as a tag. Use Chinese tags when appropriate.
TOC (Table of Contents)
Add after frontmatter, before the first heading:
* 目录
{:toc}
---
This uses Jekyll/Kramdown's automatic TOC generation. The --- adds a visual separator.
Heading Structure
Source → Target Mapping
| Source Style |
Target Style |
Reason |
## 1. 搜索工具 |
# 搜索工具 |
Remove numbering, use flat # headings for top-level sections |
### 1.1 GlobTool |
## GlobTool（文件搜索） |
Demote one level, keep parenthetical description |
#### 1.1.1 Detail |
### Detail |
Demote one level accordingly |
## 结论 |
# 总结 |
Use 总结 instead of 结论 for consistency |
Heading Level Rules
# = top-level section (h1) — used for major sections## = subsection (h2) — used for individual items/tools### = sub-subsection (h3) — used for details under an item- Never use
#### or deeper unless the source absolutely requires it
Numbering
- Remove section numbers from headings (e.g., "1.1 GlobTool" → "GlobTool")
- Numbers add no value in a blog TOC; the auto-generated TOC handles navigation
Content Adjustments
What to Keep As-Is
- Code blocks and their language annotations
- Tables
- Lists
- Bold/italic formatting
- Technical content and explanations
What to Adjust
| Change |
Example |
| Section heading numbering → remove |
## 1. 搜索工具 → # 搜索工具 |
结论 → 总结 |
More common in Chinese blog posts |
| Reference links → blockquote |
## 参考链接 → > 参考文档：[Title](URL) |
| Nested heading levels → demote |
h2→h1, h3→h2, h4→h3 |
Language
- Keep the original language of the source content (Chinese stays Chinese, English stays English)
- Frontmatter
title and description should match the article's language
Workflow
1. Read the source content
2. Detect or ask for the target blog repository path
3. Scan recent posts in _posts/ to learn:
- Category and tag conventions
- Frontmatter field order
- Any custom fields
4. Generate the slug from the article title (lowercase, hyphens, Chinese pinyin or English)
5. Determine the filename: YYYY-MM-DD-<slug>.md
- Use today's date unless user specifies otherwise
6. Transform the content:
a. Add Jekyll frontmatter
b. Add TOC marker
c. Restructure headings (remove numbers, adjust levels)
d. Adjust section names (结论→总结, etc.)
e. Convert reference section to blockquote format
7. Write the file to _posts/
8. Report the file path to the user
Slug Generation Rules
For the filename <slug>.md:
- If the title is in English: use lowercase, spaces→hyphens, strip special chars
- If the title is in Chinese: extract key terms and convert to pinyin, OR use a short English summary
- Keep slugs under 60 characters
- Use hyphens as separators, never underscores
Examples:
- "Claude Code 工具使用指南与实现原理" →
claude-code-tools-guide
- "AI Agent 对比" →
claude-code-agents-comparison
- "Token 估算方法" →
estimate-tokens
Decision UI
When the blog repository path is ambiguous, use AskUserQuestion to confirm:
- question: "博客文章要发布到哪个目录？"
- header: "博客路径"
- options: auto-detected paths + "Other"
When category/tags are unclear, propose based on content analysis and let the user confirm or adjust.
Edge Cases
- Source is not markdown: Read the content anyway and convert to markdown format
- Source has images: Keep image references as-is; warn user if images may need to be copied to the blog's assets directory
- Source already has frontmatter: Merge/replace with Jekyll frontmatter, preserve any custom fields that match the blog's conventions
- Duplicate slug: Append a numeric suffix (e.g.,
claude-code-tools-guide-2)
1---2name: create-blog3description: Use when creating or converting a blog post for a Jekyll blog, or when the user mentions 博客、blog、写博客、发文章、迁移文章. Converts source content into Jekyll-formatted blog posts with proper frontmatter, TOC, and heading structure.4---56# Create Blog Post78Convert source content (markdown files, notes, documents) into Jekyll-formatted blog posts.910## When to Use1112- User wants to create a new blog post13- User wants to migrate/convert an existing article to their Jekyll blog14- User mentions "博客", "blog", "写博客", "发文章", "迁移文章"1516## Blog Configuration1718Detect blog settings from the target repository:19201. **Find the blog repo**: Look in sibling directories of the current project, or ask the user. Common patterns: `~/code/<username>.github.io/`, `~/code/<username>.github.com/`212. **Posts directory**: `_posts/` inside the blog root223. **Naming convention**: `YYYY-MM-DD-<slug>.md`234. **Existing categories/tags**: Scan recent posts in `_posts/` to infer conventions2425## Frontmatter Format2627Every blog post must start with this frontmatter:2829```yaml30---31layout: post32title: "<文章标题>"33description: "<一句话摘要，用于 SEO 和列表预览>"34category: "<分类>"35tags: ["<标签1>", "<标签2>", ...]36---37```3839### Rules4041- **title**: Chinese, enclosed in double quotes. Concise and descriptive.42- **description**: Chinese, one sentence summarizing the article. Used for SEO meta description.43- **category**: Infer from the article topic. Check existing posts for consistency. Common values: "AI", "编程", "工具", "架构", etc.44- **tags**: Array of 2-5 relevant tags. Include the category as a tag. Use Chinese tags when appropriate.4546## TOC (Table of Contents)4748Add after frontmatter, before the first heading:4950```markdown51* 目录52{:toc}5354---55```5657This uses Jekyll/Kramdown's automatic TOC generation. The `---` adds a visual separator.5859## Heading Structure6061### Source → Target Mapping6263| Source Style | Target Style | Reason |64|---|---|---|65| `## 1. 搜索工具` | `# 搜索工具` | Remove numbering, use flat `#` headings for top-level sections |66| `### 1.1 GlobTool` | `## GlobTool（文件搜索）` | Demote one level, keep parenthetical description |67| `#### 1.1.1 Detail` | `### Detail` | Demote one level accordingly |68| `## 结论` | `# 总结` | Use 总结 instead of 结论 for consistency |6970### Heading Level Rules71721. `#` = top-level section (h1) — used for major sections732. `##` = subsection (h2) — used for individual items/tools743. `###` = sub-subsection (h3) — used for details under an item754. Never use `####` or deeper unless the source absolutely requires it7677### Numbering7879- Remove section numbers from headings (e.g., "1.1 GlobTool" → "GlobTool")80- Numbers add no value in a blog TOC; the auto-generated TOC handles navigation8182## Content Adjustments8384### What to Keep As-Is8586- Code blocks and their language annotations87- Tables88- Lists89- Bold/italic formatting90- Technical content and explanations9192### What to Adjust9394| Change | Example |95|---|---|96| Section heading numbering → remove | `## 1. 搜索工具` → `# 搜索工具` |97| `结论` → `总结` | More common in Chinese blog posts |98| Reference links → blockquote | `## 参考链接` → `> 参考文档：[Title](URL)` |99| Nested heading levels → demote | h2→h1, h3→h2, h4→h3 |100101### Language102103- Keep the original language of the source content (Chinese stays Chinese, English stays English)104- Frontmatter `title` and `description` should match the article's language105106## Workflow107108```1091. Read the source content1102. Detect or ask for the target blog repository path1113. Scan recent posts in _posts/ to learn:112 - Category and tag conventions113 - Frontmatter field order114 - Any custom fields1154. Generate the slug from the article title (lowercase, hyphens, Chinese pinyin or English)1165. Determine the filename: YYYY-MM-DD-<slug>.md117 - Use today's date unless user specifies otherwise1186. Transform the content:119 a. Add Jekyll frontmatter120 b. Add TOC marker121 c. Restructure headings (remove numbers, adjust levels)122 d. Adjust section names (结论→总结, etc.)123 e. Convert reference section to blockquote format1247. Write the file to _posts/1258. Report the file path to the user126```127128## Slug Generation Rules129130For the filename `<slug>.md`:1311321. If the title is in English: use lowercase, spaces→hyphens, strip special chars1332. If the title is in Chinese: extract key terms and convert to pinyin, OR use a short English summary1343. Keep slugs under 60 characters1354. Use hyphens as separators, never underscores136137Examples:138- "Claude Code 工具使用指南与实现原理" → `claude-code-tools-guide`139- "AI Agent 对比" → `claude-code-agents-comparison`140- "Token 估算方法" → `estimate-tokens`141142## Decision UI143144When the blog repository path is ambiguous, use AskUserQuestion to confirm:145146- question: "博客文章要发布到哪个目录？"147- header: "博客路径"148- options: auto-detected paths + "Other"149150When category/tags are unclear, propose based on content analysis and let the user confirm or adjust.151152## Edge Cases153154- **Source is not markdown**: Read the content anyway and convert to markdown format155- **Source has images**: Keep image references as-is; warn user if images may need to be copied to the blog's assets directory156- **Source already has frontmatter**: Merge/replace with Jekyll frontmatter, preserve any custom fields that match the blog's conventions157- **Duplicate slug**: Append a numeric suffix (e.g., `claude-code-tools-guide-2`)
mnhkahn