1# X Articles - Detailed Guide
2 
3Publish Markdown articles to X Articles editor with rich text formatting and images.
4 
5## Prerequisites
6 
7- X Premium subscription (required for Articles)
8- Google Chrome installed
9- `bun` installed
10 
11## Usage
12 
13```bash
14# Publish markdown article (preview mode)
15${BUN_X} {baseDir}/scripts/x-article.ts article.md
16 
17# With custom cover image
18${BUN_X} {baseDir}/scripts/x-article.ts article.md --cover ./cover.jpg
19 
20# Actually publish
21${BUN_X} {baseDir}/scripts/x-article.ts article.md --submit
22```
23 
24## Markdown Format
25 
26```markdown
27---
28title: My Article Title
29cover_image: /path/to/cover.jpg
30---
31 
32# Title (becomes article title)
33 
34Regular paragraph text with **bold** and *italic*.
35 
36## Section Header
37 
38More content here.
39 
40![Image alt text](./image.png)
41 
42- List item 1
43- List item 2
44 
451. Numbered item
462. Another item
47 
48> Blockquote text
49 
50[Link text](https://example.com)
51 
52\`\`\`
53Code blocks become blockquotes (X doesn't support code)
54\`\`\`
55```
56 
57## Frontmatter Fields
58 
59| Field | Description |
60|-------|-------------|
61| `title` | Article title (or uses first H1) |
62| `cover_image` | Cover image path or URL |
63| `cover` | Alias for cover_image |
64| `image` | Alias for cover_image |
65 
66## Image Handling
67 
681. **Cover Image**: First image or `cover_image` from frontmatter
692. **Remote Images**: Automatically downloaded to temp directory
703. **Placeholders**: Images in content use `XIMGPH_N` format
714. **Insertion**: Placeholders are found, selected, and replaced with actual images
72 
73## Markdown to HTML Script
74 
75Convert markdown and inspect structure:
76 
77```bash
78# Get JSON with all metadata
79${BUN_X} {baseDir}/scripts/md-to-html.ts article.md
80 
81# Output HTML only
82${BUN_X} {baseDir}/scripts/md-to-html.ts article.md --html-only
83 
84# Save HTML to file
85${BUN_X} {baseDir}/scripts/md-to-html.ts article.md --save-html /tmp/article.html
86```
87 
88JSON output:
89```json
90{
91  "title": "Article Title",
92  "coverImage": "/path/to/cover.jpg",
93  "contentImages": [
94    {
95      "placeholder": "XIMGPH_1",
96      "localPath": "/tmp/x-article-images/img.png",
97      "blockIndex": 5
98    }
99  ],
100  "html": "<p>Content...</p>",
101  "totalBlocks": 20
102}
103```
104 
105## Supported Formatting
106 
107| Markdown | HTML Output |
108|----------|-------------|
109| `# H1` | Title only (not in body) |
110| `## H2` - `###### H6` | `<h2>` |
111| `**bold**` | `<strong>` |
112| `*italic*` | `<em>` |
113| `[text](url)` | `<a href>` |
114| `> quote` | `<blockquote>` |
115| `` `code` `` | `<code>` |
116| ```` ``` ```` | `<blockquote>` (X limitation) |
117| `- item` | `<ul><li>` |
118| `1. item` | `<ol><li>` |
119| `![](img)` | Image placeholder |
120 
121## Workflow
122 
1231. **Parse Markdown**: Extract title, cover, content images, generate HTML
1242. **Launch Chrome**: Real browser with CDP, persistent login
1253. **Navigate**: Open `x.com/compose/articles`
1264. **Create Article**: Click create button if on list page
1275. **Upload Cover**: Use file input for cover image
1286. **Fill Title**: Type title into title field
1297. **Paste Content**: Copy HTML to clipboard, paste into editor
1308. **Insert Images**: For each placeholder (reverse order):
131   - Find placeholder text in editor
132   - Select the placeholder
133   - Copy image to clipboard
134   - Paste to replace selection
1359. **Post-Composition Check** (automatic):
136   - Scan editor for remaining `XIMGPH_` placeholders
137   - Compare expected vs actual image count
138   - Warn if issues found
13910. **Review**: Browser stays open for 60s preview
14011. **Publish**: Only with `--submit` flag
141 
142## Example Session
143 
144```
145User: /post-to-x article ./blog/my-post.md --cover ./thumbnail.png
146 
147Claude:
1481. Parses markdown: title="My Post", 3 content images
1492. Launches Chrome with CDP
1503. Navigates to x.com/compose/articles
1514. Clicks create button
1525. Uploads thumbnail.png as cover
1536. Fills title "My Post"
1547. Pastes HTML content
1558. Inserts 3 images at placeholder positions
1569. Reports: "Article composed. Review and use --submit to publish."
157```
158 
159## Troubleshooting
160 
161- **No create button**: Ensure X Premium subscription is active
162- **Cover upload fails**: Check file path and format (PNG, JPEG)
163- **Images not inserting**: Verify placeholders exist in pasted content
164- **Content not pasting**: Check HTML clipboard: `${BUN_X} {baseDir}/scripts/copy-to-clipboard.ts html --file /tmp/test.html`
165 
166## How It Works
167 
1681. `md-to-html.ts` converts Markdown to HTML:
169   - Extracts frontmatter (title, cover)
170   - Converts markdown to HTML
171   - Replaces images with unique placeholders
172   - Downloads remote images locally
173   - Returns structured JSON
174 
1752. `x-article.ts` publishes via CDP:
176   - Launches real Chrome (bypasses detection)
177   - Uses persistent profile (saved login)
178   - Navigates and fills editor via DOM manipulation
179   - Pastes HTML from system clipboard
180   - Finds/selects/replaces each image placeholder
181