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)
npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md

# With custom cover image
npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md --cover ./cover.jpg

# Actually publish
npx -y bun ${SKILL_DIR}/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 [[IMAGE_PLACEHOLDER_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
npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md

# Output HTML only
npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md --html-only

# Save HTML to file
npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md --save-html /tmp/article.html

JSON output:

{
  "title": "Article Title",
  "coverImage": "/path/to/cover.jpg",
  "contentImages": [
    {
      "placeholder": "[[IMAGE_PLACEHOLDER_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. Review: Browser stays open for 60s preview

10. 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: npx -y bun ${SKILL_DIR}/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