Publish X Article

Publish X Article

Publish Markdown content to X (Twitter) Articles editor, preserving formatting with rich text conversion. Automatically handles X Premium limitations by converting unsupported elements to images.

Credits

This skill is inspired by and based on wshuyi/x-article-publisher-skill. Thank you to the original author for the foundational work.

Interactive Setup: Ask Subscription Type

IMPORTANT: Before processing the article, ask the user about their X subscription type if not already known.

Prompt the User

Before publishing, I need to know your X subscription type to handle formatting correctly:

1. **X Premium** - Basic tier ($8/month)
2. **X Premium+** - Plus tier ($16/month)

Which subscription do you have? (Premium / Premium+)

For Chinese users:

在发布之前，我需要了解您的 X 订阅类型以正确处理格式：

1. **X Premium** - 基础版 ($8/月)
2. **X Premium+** - 高级版 ($16/月)

您使用的是哪个版本？(Premium / Premium+)

Remember the Answer

Once the user answers, remember their subscription type for the rest of the session. Don't ask again unless they explicitly want to change it.

X Subscription Feature Comparison

Pre-Processing Required by Subscription

X Premium (Basic):

• Convert H3+ headers → H2 or bold
• Convert tables → PNG images
• Convert mermaid → PNG images

X Premium+ (Plus):

• Keep H3+ headers as-is
• Keep tables as-is (rendered natively)
• Convert mermaid → PNG images (still not supported)

Prerequisites

• Playwright MCP for browser automation
• User logged into X with Premium subscription
• Python 3.9+ with dependencies:
• macOS: pip install Pillow pyobjc-framework-Cocoa markdown
• Windows: pip install Pillow pywin32 clip-util markdown
• diagram-to-image skill (for converting tables/mermaid to PNG via diagramless.xyz API)

Scripts

Located in ~/.claude/skills/publish-x-article/scripts/:

parse_markdown.py

Parse Markdown and extract structured data:

python parse_markdown.py <markdown_file> [--output json|html] [--html-only]

Returns JSON with: title, cover_image, content_images (with block_index for positioning), html, total_blocks

copy_to_clipboard.py

Copy image or HTML to system clipboard:

# Copy image (with optional compression)
python copy_to_clipboard.py image /path/to/image.jpg [--quality 80]

# Copy HTML for rich text paste
python copy_to_clipboard.py html --file /path/to/content.html

diagram-to-image.mjs (from diagram-to-image skill)

Convert Mermaid diagrams and Markdown tables to PNG images via diagramless.xyz API:

node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table.png
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram.png --theme ocean

Pre-Processing: Handle Unsupported Elements

Before publishing, scan the Markdown for unsupported elements and convert them to images.

Step 0: Analyze Content for Limitations

# Check the markdown file for unsupported elements
cat /path/to/article.md

Look for:

1. Deep headers (H3+): ###, ####, etc.
2. Markdown tables: Lines with | characters forming table structure
3. Mermaid code blocks: `mermaid

Converting Unsupported Elements to Images

1. Markdown Tables → PNG

When a table is detected:

# 1. Extract table to temp file
cat > /tmp/table.md << 'TABLE_EOF'
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
TABLE_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table-001.png

# 3. Replace table in markdown with image reference
# ![Table description](/tmp/table-001.png)

2. Mermaid Diagrams → PNG

When a mermaid block is detected:

# 1. Extract mermaid to temp file
cat > /tmp/diagram.mmd << 'MERMAID_EOF'
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
MERMAID_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram-001.png

# 3. Replace mermaid block in markdown with image reference
# ![Diagram description](/tmp/diagram-001.png)

3. Deep Headers (H3+) → Simplified Structure

Goal: Preserve the article's logical structure and readability while working within X Premium's H2-only limitation.

Guidelines for the AI:

When you encounter H3, H4, or deeper headers in a Premium user's article, think about what the author intended:

• If the header introduces a distinct subtopic under a section, convert it to bold text as a paragraph opener. This maintains visual hierarchy without breaking X's formatting.

• If the header is a major section that happens to be H3, consider promoting it to H2 — but only if this doesn't create a flat, meaningless structure. The article should still flow logically.

• If there's a deep hierarchy (H2 → H3 → H4), flatten thoughtfully:
• Keep H2 as H2
• Convert H3 to bold paragraph
• Convert H4 to italic or just merge into the paragraph naturally

• Preserve meaning over structure. A header like ### Why This Matters might become a bold lead-in: **Why does this matter?** followed by the content. Use your judgment.

• Read the content. If an H3 header is just "Example" or "Note", it might work better as a blockquote or inline emphasis rather than a standalone bold line.

The goal is not mechanical conversion — it's creating an article that reads well on X while honoring the author's intent.

Pre-Processing Workflow

Before publishing, read through the article and prepare it for X:

1. Understand the article's structure — Read it first. What are the main sections? How does the author use headers to organize ideas?

1. Handle tables and mermaid diagrams — These need to become images. Extract each one, convert to PNG, and note where they should be inserted.

1. Adapt headers for the subscription tier:

• For Premium+ users: Keep headers as-is (H3+ supported)
• For Premium users: Thoughtfully restructure H3+ headers while preserving the article's flow and intent (see guidelines above)

1. Create the modified markdown — Save your adapted version to a temp file, ready for parsing.

The goal is an article that reads naturally on X, not a mechanically transformed document.

Main Workflow

Strategy: "先文后图后分割线" (Text First, Images Second, Dividers Last)

For articles with images and dividers, paste ALL text content first, then insert images and dividers at correct positions using block index.

1. Pre-process: Convert tables/mermaid to images, flatten deep headers
2. Parse modified Markdown with Python script → get title, images, dividers (all with block_index), HTML
3. Navigate to X Articles editor
4. Upload cover image (first image)
5. Fill title
6. Copy HTML to clipboard (Python) → Paste with Cmd+V
7. Insert content images at positions specified by block_index
8. Insert dividers at positions specified by block_index (via Insert > Divider menu)
9. Save as draft (NEVER auto-publish)

高效执行原则 (Efficiency Guidelines)

目标: 最小化操作之间的等待时间，实现流畅的自动化体验。

1. 避免不必要的 browser_snapshot

大多数浏览器操作（click, type, press_key 等）都会在返回结果中包含页面状态。不要在每次操作后单独调用 browser_snapshot，直接使用操作返回的页面状态即可。

❌ 错误做法：
browser_click → browser_snapshot → 分析 → browser_click → browser_snapshot → ...

✅ 正确做法：