JimLiu-baoyu-skills/skills/baoyu-post-to-x/references/articles.md

X Articles - Detailed Guide

Publish Markdown articles to X Articles editor with rich text formatting and images.

Prerequisites

• X Premium subscription (required for Articles)
• Google Chrome installed
• bun installed

Usage

# Publish markdown article (preview mode)
${BUN_X} {baseDir}/scripts/x-article.ts article.md

# With custom cover image
${BUN_X} {baseDir}/scripts/x-article.ts article.md --cover ./cover.jpg

# Actually publish
${BUN_X} {baseDir}/scripts/x-article.ts article.md --submit

Markdown Format

---
title: My Article Title
cover_image: /path/to/cover.jpg
---

# Title (becomes article title)

Regular paragraph text with **bold** and *italic*.

## Section Header

More content here.

![Image alt text](./image.png)

- List item 1
- List item 2

1. Numbered item
2. Another item

> Blockquote text

[Link text](https://example.com)

\`\`\`
Code blocks become blockquotes (X doesn't support code)
\`\`\`

Frontmatter Fields

Field	Description
title	Article title (or uses first H1)
cover_image	Cover image path or URL
cover	Alias for cover_image
image	Alias for cover_image

Image Handling

1. Cover Image: First image or cover_image from frontmatter
2. Remote Images: Automatically downloaded to temp directory
3. Placeholders: Images in content use XIMGPH_N format
4. Insertion: Placeholders are found, selected, and replaced with actual images

Markdown to HTML Script

Convert markdown and inspect structure:

# Get JSON with all metadata
${BUN_X} {baseDir}/scripts/md-to-html.ts article.md

# Output HTML only
${BUN_X} {baseDir}/scripts/md-to-html.ts article.md --html-only

# Save HTML to file
${BUN_X} {baseDir}/scripts/md-to-html.ts article.md --save-html /tmp/article.html

JSON output:

{
  "title": "Article Title",
  "coverImage": "/path/to/cover.jpg",
  "contentImages": [
    {
      "placeholder": "XIMGPH_1",
      "localPath": "/tmp/x-article-images/img.png",
      "blockIndex": 5
    }
  ],
  "html": "<p>Content...</p>",
  "totalBlocks": 20
}

Supported Formatting

Markdown	HTML Output
# H1	Title only (not in body)
## H2 - ###### H6	<h2>
**bold**	<strong>
*italic*	<em>
[text](url)	<a href>
> quote	<blockquote>
`code`	<code>
```	<blockquote> (X limitation)
- item	<ul><li>
1. item	<ol><li>
	Image placeholder

Workflow

1. Parse Markdown: Extract title, cover, content images, generate HTML
2. Launch Chrome: Real browser with CDP, persistent login
3. Navigate: Open x.com/compose/articles
4. Create Article: Click create button if on list page
5. Upload Cover: Use file input for cover image
6. Fill Title: Type title into title field
7. Paste Content: Copy HTML to clipboard, paste into editor
8. Insert Images: For each placeholder (reverse order):
   • Find placeholder text in editor
   • Select the placeholder
   • Copy image to clipboard
   • Paste to replace selection
9. Post-Composition Check (automatic):
   • Scan editor for remaining XIMGPH_ placeholders
   • Compare expected vs actual image count
   • Warn if issues found
10. Review: Browser stays open for 60s preview
11. Publish: Only with --submit flag

Example Session

User: /post-to-x article ./blog/my-post.md --cover ./thumbnail.png

Claude:
1. Parses markdown: title="My Post", 3 content images
2. Launches Chrome with CDP
3. Navigates to x.com/compose/articles
4. Clicks create button
5. Uploads thumbnail.png as cover
6. Fills title "My Post"
7. Pastes HTML content
8. Inserts 3 images at placeholder positions
9. Reports: "Article composed. Review and use --submit to publish."

Troubleshooting

• No create button: Ensure X Premium subscription is active
• Cover upload fails: Check file path and format (PNG, JPEG)
• Images not inserting: Verify placeholders exist in pasted content
• Content not pasting: Check HTML clipboard: ${BUN_X} {baseDir}/scripts/copy-to-clipboard.ts html --file /tmp/test.html

How It Works

1. md-to-html.ts converts Markdown to HTML:

   • Extracts frontmatter (title, cover)
   • Converts markdown to HTML
   • Replaces images with unique placeholders
   • Downloads remote images locally
   • Returns structured JSON

2. x-article.ts publishes via CDP:

   • Launches real Chrome (bypasses detection)
   • Uses persistent profile (saved login)
   • Navigates and fills editor via DOM manipulation
   • Pastes HTML from system clipboard
   • Finds/selects/replaces each image placeholder