---

name: post-writer description: "Convert markdown article drafts to MDX blog posts with bilingual support (Chinese and English). Use when user provides a markdown article and wants to publish it as a blog post on the website. Handles frontmatter generation, MDX syntax validation, and full translation."

Post Writer Skill

Convert markdown article drafts into website-ready MDX blog posts with bilingual support.

Workflow Overview

1. Gather inputs from user
2. Read reference blog to learn format
3. Read article draft and analyze content
4. Clarify requirements via AskUserQuestion if needed
5. Create Chinese version (.zh.mdx) - preserve original content
6. Apply layout optimization - make article visually appealing
7. Create English version (.mdx) - full translation with same layout
8. Insert showcase images at article end (figure + scene)
9. Validate MDX syntax and fix issues
10. Save to content/posts/

Required Inputs

Ask user for these if not provided:

Step-by-Step Process

Step 1: Read Reference Blog

Read the reference blog post to learn:

• Frontmatter structure (title, description, created_at, author_name, author_image, image)
• Content formatting conventions
• File naming patterns

Step 2: Read and Analyze Article Draft

Read the source markdown file completely. Identify:

• Article title and main topic
• Key sections and structure
• Potential MDX syntax issues (see mdx-syntax-guide.md)
• Contact information that may need formatting

Step 3: Clarify Requirements

Use AskUserQuestion to clarify:

• Filename: Suggest a kebab-case filename based on content
• Phone numbers: If special characters are used, ask whether to convert to digits
• Date: Confirm the publication date
• Author info: Confirm author name if not obvious

Step 4: Create Frontmatter

Generate SEO-optimized frontmatter:

Copy---
title: "Article Title Here"
description: "Compelling description for SEO (150-200 chars)"
created_at: YYYY-MM-DD
author_name: Author Name
author_image: /logo.png
image: /imgs/post-imgs/YYYYMMDD/cover.jpg
---

Critical: Always quote title and description if they contain special characters (colon, question mark, exclamation mark, quotes, etc.)

Step 5: Create Chinese Version

File: content/posts/{filename}.zh.mdx

• Preserve original article content completely
• Add frontmatter with Chinese title/description
• Fix MDX syntax issues (see validation checklist)
• Apply layout optimization (see Step 5.5)

Step 5.5: Layout Optimization (IMPORTANT)

Apply these formatting techniques to make articles visually appealing and easy to read.

---

Simple & Clean Design System

This project uses a simple, text-focused design for blog posts. The design emphasizes readability, comfortable line spacing, and minimal styling. Avoid overly complex layouts that look "AI-generated".

Design Principles

1. Text-Focused - Content is king, minimal decorative elements
2. Comfortable Reading - Relaxed line spacing, no visual pressure
3. Brand Color Accent - Use #8bbc40 sparingly for emphasis
4. Dark Mode Support - All styled elements include dark: variants
5. Natural Feel - Avoid looking too "AI-generated" or overly designed

Brand Color

Copy#8bbc40 (Green)

Use this color only for key accents like H3 left borders.

---

Article Structure

Wrap entire article content in a relaxed line-height container:

Copy<div className="leading-relaxed">

# Article Title

Article content here...

</div>

---

Table of Contents (TOC) Compatibility (CRITICAL)

⚠️ JSX heading tags (<h2>, <h3>) will NOT appear in the sidebar Table of Contents!

The MDX TOC generator only recognizes standard Markdown heading syntax (##, ###). If you use JSX heading tags, even if the build succeeds, those headings will be invisible in the TOC sidebar, making navigation impossible for readers.

Problem:

Copy<h2 className="styled-heading">Section Title</h2>   → ❌ NOT in TOC
<h3 className="styled-heading">Subsection</h3>     → ❌ NOT in TOC

Solution:

Copy## Section Title      → ✅ Appears in TOC
### Subsection        → ✅ Appears in TOC

Why this matters:

• Blog posts rely on TOC for navigation
• Readers expect to see all sections in the sidebar
• Missing TOC entries make long articles hard to navigate
• This is a silent failure - build succeeds but TOC is broken

---

H2 Styling

⚠️ CRITICAL: Use standard Markdown ## for H2 headers, NOT JSX <h2> tags!

JSX <h2> tags with Tailwind className (like px-4, py-2, rounded-lg) will cause MDX compilation errors. The MDX parser misinterprets numeric values in class names.

❌ DO NOT USE (will break build):

Copy<h2 className="bg-slate-100 dark:bg-slate-800 px-4 py-2 rounded-lg">Title</h2>

✅ USE THIS INSTEAD:

Copy## Section Title

Styling H2 via CSS: If custom H2 styling is needed, configure it globally in the theme's CSS/MDX components rather than inline JSX.

---

H3 Styling

⚠️ CRITICAL: Use standard Markdown ### for H3 headers, NOT JSX <h3> tags!

JSX <h3> tags with Tailwind className (like px-3, py-1.5, text-[#8bbc40]) will cause MDX compilation errors. The MDX parser misinterprets numeric values in class names (e.g., -3 in px-3) as invalid JSX expressions.

❌ DO NOT USE (will break build):

Copy<h3 className="bg-slate-50 dark:bg-slate-900 px-3 py-1.5 rounded-md text-[#8bbc40]">Title</h3>

✅ USE THIS INSTEAD:

Copy### Subsection Title

Why this happens:

• MDX parser sees px-3 and interprets -3 as part of a JSX expression
• Error message: Unexpected character '3' before name
• This is a known MDX limitation with complex className values

Styling H3 via CSS: If custom H3 styling is needed, configure it globally in the theme's CSS/MDX components rather than inline JSX.

---

Basic Formatting (Preferred)

Use standard Markdown for most content to maintain a natural, readable feel.

Blockquotes for Customer Quotes

Copy> "Customer quote or important statement..."
>
> — Customer Name

Section Dividers

Copy---

Tables for Data/Specifications

Copy| Parameter | Value |
|-----------|-------|
| Temperature | ≤±0.5°C |
| Humidity | ≤±5%RH |

Bullet Lists

Copy- Point one
- Point two
- Point three

Bold for Emphasis

Copy**Important text here**

Images with Alt Text

Copy![Image description](/imgs/post-imgs/YYYYMMDD/image.png)

---

What to Avoid

• ❌ Too many gradient backgrounds
• ❌ Complex card layouts with multiple colors
• ❌ Excessive use of colored text
• ❌ Over-styled statistics blocks
• ❌ Designs that look "AI-generated"
• ❌ Too many block-level styled elements

What to Use

• ✅ Standard Markdown formatting
• ✅ Simple H2/H3 with subtle backgrounds
• ✅ Blockquotes for quotes
• ✅ Tables for structured data
• ✅ Bullet lists for features/points
• ✅ Bold text for emphasis
• ✅ Section dividers (---) between major sections

---

Step 6: Create English Version

File: content/posts/{filename}.mdx

• Translate entire article to English
• Maintain same structure and formatting
• Translate frontmatter title/description
• Fix MDX syntax issues
• Apply same layout optimization as Chinese version

Step 7: Insert Showcase Images

Add a "Project Results Showcase" section at the end of the article (before company signature):

Chinese version:

Copy## 📊 项目成果展示

![核心指标对比图](/imgs/post-imgs/YYYYMMDD/figures.png)

![项目实景](/imgs/post-imgs/YYYYMMDD/scene.png)

English version:

Copy## 📊 Project Results Showcase

![Core Performance Metrics Comparison](/imgs/post-imgs/YYYYMMDD/figures.png)

![Project Scene](/imgs/post-imgs/YYYYMMDD/scene.png)

Placement: Insert after contact information section, before the final --- separator and company signature.

Step 8: MDX Syntax Validation

Before saving, check and fix these issues:

CRITICAL CHECKS:

• < symbols → Replace with < or add spaces: < 100V → < 100V
• {< combinations → Never allow, will break MDX
• > in content → Usually OK, but escape if inside JSX context
• { and } → Escape or avoid in regular text
• Frontmatter colons → Quote values containing :

See references/mdx-syntax-guide.md for complete guide.

Step 9: Save and Verify

1. Write both files to content/posts/
2. Verify files were created successfully
3. Run grep to confirm no remaining syntax issues

Step 10: Pre-Push Mandatory Validation (CRITICAL)

⚠️ NEVER git push without completing this step!

Before committing and pushing, you MUST run local build validation to catch MDX syntax errors:

Copy# Clear cache and run build
rm -rf .next && pnpm build

If build fails, check for these common issues:

1. Bare < followed by numbers (MOST COMMON ERROR):

   Copy# Error example:
   湿度<35%     → MDX thinks <35% is a JSX tag
   电阻<4Ω     → MDX thinks <4Ω is a JSX tag
   
   # Fix: Use &lt; entity
   湿度 &lt; 35%
   电阻 &lt; 4Ω
   

2. JSX tags with Tailwind className containing numbers:

   Copy# Error example:
   <h2 className="px-4 py-2">   → Numbers in className break MDX
   
   # Fix: Use standard Markdown
   ## Title
   

Quick validation commands:

Copy# Find bare < followed by numbers (potential issues)
grep -n "<[0-9]" content/posts/your-file.mdx

# Find JSX tags with className
grep -n "className=" content/posts/your-file.mdx

Only proceed with git push after build succeeds!

Output Files

Copycontent/posts/
├── {filename}.zh.mdx   # Chinese version
└── {filename}.mdx      # English version

Quality Checklist

• Frontmatter complete and properly quoted
• Cover image path correct
• Figure image inserted at article end
• Scene image inserted at article end
• Date format: YYYY-MM-DD
• Chinese version preserves original content
• English version is complete translation
• All MDX syntax issues resolved
• No {< or bare < symbols in content
• All headings use standard Markdown (##, ###), NOT JSX tags (for TOC compatibility)
• Tables render correctly
• Emoji preserved
• Contact info formatted correctly