tuzi-format-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Formatter

Markdown格式化工具

Transforms plain text or markdown files into well-structured markdown with proper frontmatter, formatting, and typography.

将纯文本或Markdown文件转换为结构清晰的Markdown格式，包含规范的frontmatter、格式排版和文本样式。

Script Directory

脚本目录

Scripts in

scripts/

subdirectory. Replace

${SKILL_DIR}

with this SKILL.md's directory path.

Script	Purpose
`scripts/main.ts`	Main entry point with CLI options (uses remark-cjk-friendly for CJK emphasis)
`scripts/quotes.ts`	Replace ASCII quotes with fullwidth quotes
`scripts/autocorrect.ts`	Add CJK/English spacing via autocorrect

脚本位于

scripts/

子目录中。将

${SKILL_DIR}

替换为当前SKILL.md所在的目录路径。

脚本	用途
`scripts/main.ts`	主入口点，带有CLI选项（使用remark-cjk-friendly处理CJK强调格式）
`scripts/quotes.ts`	将ASCII引号替换为全角引号
`scripts/autocorrect.ts`	通过autocorrect添加CJK/英文混排空格

Preferences (EXTEND.md)

偏好设置（EXTEND.md）

Use Bash to check EXTEND.md existence (priority order):

bash

undefined

使用Bash检查EXTEND.md是否存在（优先级顺序）：

bash

undefined

Check project-level first

优先检查项目级配置

test -f .tuzi-skills/tuzi-format-markdown/EXTEND.md && echo "project"

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)

然后检查用户级配置（跨平台：$HOME适用于macOS/Linux/WSL）

test -f "$HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md" && echo "user"


┌──────────────────────────────────────────────────────────┬───────────────────┐
│                           Path                           │     Location      │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-format-markdown/EXTEND.md            │ Project directory │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md      │ User home         │
└──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ Use defaults                                                              │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Default formatting options | Summary length preferences

test -f "$HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md" && echo "user"


┌──────────────────────────────────────────────────────────┬───────────────────┐
│ 路径 │ 位置 │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-format-markdown/EXTEND.md            │ 项目目录 │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md      │ 用户主目录 │
└──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│ 结果 │ 操作 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 找到 │ 读取、解析并应用配置 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到 │ 使用默认配置 │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md支持**：默认格式化选项 | 摘要长度偏好设置

Usage

使用方法

Claude performs content analysis and formatting (Steps 1-6), then runs the script for typography fixes (Step 7).

Claude会先进行内容分析和格式化（步骤1-6），然后运行脚本进行排版修复（步骤7）。

Workflow

工作流程

Step 1: Read Source File

步骤1：读取源文件

Read the user-specified markdown or plain text file.

读取用户指定的Markdown或纯文本文件。

Step 1.5: Detect Content Type & Confirm

步骤1.5：检测内容类型并确认

Content Type Detection:

Indicator	Classification
Has `---` YAML frontmatter	Markdown
Has `#` , `##` , `###` headings	Markdown
Has `bold` , `italic`	Markdown
Has `-` or `1.` lists	Markdown
Has ``` code blocks	Markdown
Has `>` blockquotes	Markdown
None of above	Plain text

Decision Flow:

┌─────────────────┬────────────────────────────────────────────────┐ │ Content Type │ Action │ ├─────────────────┼────────────────────────────────────────────────┤ │ Plain text │ Proceed to Step 2 (format to markdown) │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ Use AskUserQuestion to confirm optimization │ └─────────────────┴────────────────────────────────────────────────┘

If Markdown detected, ask user:

Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Add/improve frontmatter, headings, bold, lists
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly

Based on user choice:

Optimize: Continue to Step 2-8 (full workflow)
Keep original: Skip Steps 2-5, copy file → Step 6-8 (run script on copy)
Typography only: Skip Steps 2-6, run Step 7 on original file directly

内容类型检测：

标识	分类
包含 `---` YAML frontmatter	Markdown
包含 `#` 、 `##` 、 `###` 标题	Markdown
包含 `加粗` 、 `斜体`	Markdown
包含 `-` 或 `1.` 列表	Markdown
包含```代码块	Markdown
包含 `>` 块引用	Markdown
以上都不满足	纯文本

决策流程：

┌─────────────────┬────────────────────────────────────────────────┐ │ 内容类型 │ 操作 │ ├─────────────────┼────────────────────────────────────────────────┤ │ 纯文本 │ 进入步骤2（格式化为Markdown） │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ 使用AskUserQuestion工具确认是否需要优化 │ └─────────────────┴────────────────────────────────────────────────┘

如果检测到Markdown，询问用户：

检测到已存在Markdown格式。您希望执行以下哪种操作？

1. 优化格式（推荐）
   - 添加/完善frontmatter、标题、加粗、列表
   - 运行排版脚本（空格、强调格式修复）
   - 输出文件：{filename}-formatted.md

2. 保留原格式
   - 保留现有Markdown结构
   - 运行排版脚本（空格、强调格式修复）
   - 输出文件：{filename}-formatted.md

3. 仅修复排版
   - 在原文件上直接运行排版脚本
   - 不创建副本，直接修改原文件

根据用户选择执行：

优化：继续执行步骤2-8（完整工作流程）
保留原格式：跳过步骤2-5，复制文件后执行步骤6-8（仅对副本运行脚本）
仅修复排版：跳过步骤2-6，直接对原文件执行步骤7

Step 2: Analyze Content Structure

步骤2：分析内容结构

Identify:

Existing title (H1
```
#
```
)
Paragraph separations
Keywords suitable for bold
Parallel content convertible to lists
Code snippets
Quotations

识别以下元素：

现有标题（H1
```
#
```
）
段落分隔
适合用加粗标记的关键词
可转换为列表的平行内容
代码片段
引用内容

Step 3: Check/Create Frontmatter

步骤3：检查/创建Frontmatter

Check for YAML frontmatter (

---

block). Create if missing.

Meta field handling:

Field	Processing
`title`	See Step 4
`slug`	Infer from file path (e.g., `posts/2026/01/10/vibe-coding/` → `vibe-coding` ) or generate from title
`summary`	Generate engaging summary (100-150 characters)
`coverImage`	Check if `imgs/cover.png` exists in same directory; if so, use relative path (also accepted: `featureImage` )

检查是否存在YAML frontmatter（

---

块），如果缺失则创建。

元字段处理：

字段	处理方式
`title`	参见步骤4
`slug`	从文件路径推导（例如： `posts/2026/01/10/vibe-coding/` → `vibe-coding` ）或根据标题生成
`summary`	生成吸引人的摘要（100-150字符）
`coverImage`	检查同一目录下是否存在 `imgs/cover.png` ；如果存在则使用相对路径（也支持 `featureImage` 字段）

Step 4: Title Handling

步骤4：标题处理

Logic:

If frontmatter already has
```
title
```
→ use it, no H1 in body
If first line is H1 → extract to frontmatter
```
title
```
, remove H1 from body
If neither exists → generate candidate titles

Title generation flow:

Generate 3 candidate titles based on content
Use
```
AskUserQuestion
```
tool:

Select a title:

1. [Title A] (Recommended)
2. [Title B]
3. [Title C]

If no selection within a few seconds, use recommended (option 1)

Title principles:

Concise, max 20 characters
Captures core message
Engaging, sparks reading interest
Accurate, avoids clickbait

Important: Once title is in frontmatter, body should NOT have H1 (avoid duplication)

逻辑：

如果frontmatter中已有
```
title
```
→ 使用该标题，正文中不再添加H1
如果第一行是H1 → 将其提取到frontmatter的
```
title
```
字段，正文中移除该H1
如果以上都不存在 → 生成候选标题

标题生成流程：

根据内容生成3个候选标题
使用
```
AskUserQuestion
```
工具询问用户：

请选择一个标题：

1. [标题A]（推荐）
2. [标题B]
3. [标题C]

如果用户在几秒内未选择，则使用推荐选项（选项1）

标题原则：

简洁，最多20字符
抓住核心内容
吸引人，激发阅读兴趣
准确，避免标题党

重要提示：标题放入frontmatter后，正文中不应再出现H1（避免重复）

Step 5: Format Processing

步骤5：格式处理

Formatting rules:

Element	Format
Titles	Use `#` , `##` , `###` hierarchy
Key points	Use `bold`
Parallel items	Convert to `-` unordered or `1.` ordered lists
Code/commands	Use `inline` or ```block```
Quotes/sayings	Use `>` blockquote
Separators	Use `---` where appropriate

Formatting principles:

Preserve original content and viewpoints
Add formatting only, do not modify text
Formatting serves readability
Avoid over-formatting

格式化规则：

元素	格式
标题	使用 `#` 、 `##` 、 `###` 层级结构
关键点	使用 `加粗`
平行内容	转换为 `-` 无序列表或 `1.` 有序列表
代码/命令	使用 `行内代码` 或 ```代码块```
引用/名言	使用 `>` 块引用
分隔符	适当位置使用 `---`

格式化原则：

保留原始内容和观点
仅添加格式，不修改文本内容
格式服务于可读性
避免过度格式化

Step 6: Save Formatted File

步骤6：保存格式化后的文件

Save as

{original-filename}-formatted.md

Examples:

```
final.md
```
→
```
final-formatted.md
```
```
draft-v1.md
```
→
```
draft-v1-formatted.md
```

If user chose "Keep original formatting" (from Step 1.5):

Copy original file to
```
{filename}-formatted.md
```
without modifications
Proceed to Step 7 for typography fixes only

Backup existing file:

{filename}-formatted.md

already exists, backup before overwriting:

bash

undefined

保存为

{original-filename}-formatted.md

示例：

```
final.md
```
→
```
final-formatted.md
```
```
draft-v1.md
```
→
```
draft-v1-formatted.md
```

如果用户选择「保留原格式」（来自步骤1.5）：

直接复制原文件到
```
{filename}-formatted.md
```
，不做任何修改
进入步骤7，仅执行排版修复

备份现有文件：

如果

{filename}-formatted.md

已存在，覆盖前先备份：

bash

undefined

Check if formatted file exists

检查格式化文件是否存在

if [ -f "{filename}-formatted.md" ]; then

Backup with timestamp

mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md" fi


Example:
- `final-formatted.md` exists → backup to `final-formatted.backup-20260128-143052.md`

if [ -f "{filename}-formatted.md" ]; then

添加时间戳备份

mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md" fi


示例：
- `final-formatted.md`已存在 → 备份为`final-formatted.backup-20260128-143052.md`

Step 7: Execute Text Formatting Script

步骤7：执行文本格式化脚本

After saving, must run the formatting script:

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts {output-file-path} [options]

Script Options:

Option	Short	Description	Default
`--quotes`	`-q`	Replace ASCII quotes with fullwidth quotes `"..."`	false
`--no-quotes`		Do not replace quotes
`--spacing`	`-s`	Add CJK/English spacing via autocorrect	true
`--no-spacing`		Do not add CJK/English spacing
`--emphasis`	`-e`	Fix CJK emphasis punctuation issues	true
`--no-emphasis`		Do not fix CJK emphasis issues
`--help`	`-h`	Show help message

Examples:

bash

undefined

保存文件后，必须运行格式化脚本：

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts {output-file-path} [options]

脚本选项：

选项	简写	描述	默认值
`--quotes`	`-q`	将ASCII引号 `"..."` 替换为全角引号 `"..."`	false
`--no-quotes`		不替换引号
`--spacing`	`-s`	通过autocorrect添加CJK/英文混排空格	true
`--no-spacing`		不添加CJK/英文混排空格
`--emphasis`	`-e`	修复CJK强调/加粗标点问题	true
`--no-emphasis`		不修复CJK强调问题
`--help`	`-h`	显示帮助信息

示例：

bash

undefined

Default: spacing + emphasis enabled, quotes disabled

默认配置：启用空格和强调修复，禁用引号替换

npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

Enable all features including quote replacement

启用所有功能，包括引号替换

npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

Only fix emphasis issues, skip spacing

仅修复强调问题，跳过空格处理

npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

Disable all processing except frontmatter formatting

禁用所有处理，仅格式化frontmatter

npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis


**Script performs (based on options):**
1. Fix CJK emphasis/bold punctuation issues (default: enabled)
2. Add CJK/English mixed text spacing via autocorrect (default: enabled)
3. Replace ASCII quotes `"..."` with fullwidth quotes `"..."` (default: disabled)
4. Format frontmatter YAML (always enabled)

npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis


**脚本执行的操作（根据选项）**：
1. 修复CJK强调/加粗标点问题（默认启用）
2. 通过autocorrect添加CJK/英文混排空格（默认启用）
3. 将ASCII引号`"..."`替换为全角引号`"..."`（默认禁用）
4. 格式化frontmatter YAML（始终启用）

Step 8: Display Results

步骤8：显示结果

**Formatting complete**

File: posts/2026/01/09/example/final-formatted.md

Changes:
- Added title: [title content]
- Added X bold markers
- Added X lists
- Added X code blocks

**格式化完成**

文件：posts/2026/01/09/example/final-formatted.md

修改内容：
- 添加标题：[标题内容]
- 添加X处加粗标记
- 添加X个列表
- 添加X个代码块

Formatting Example

格式化示例

Before:

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

After:

markdown

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

格式化前：

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

格式化后：

markdown

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

Notes

注意事项

Preserve original writing style and tone
Specify correct language for code blocks (e.g.,
```
python
```
,
```
javascript
```
)
Maintain CJK/English spacing standards
Do not add content not present in original

保留原始写作风格和语气
为代码块指定正确的语言（例如
```
python
```
、
```
javascript
```
）
遵循CJK/英文混排空格规范
不添加原始内容中没有的信息

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

通过EXTEND.md进行自定义配置。请查看偏好设置部分了解配置路径和支持的选项。