177 lines
4.5 KiB
Markdown
177 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```markdown
|
|
---
|
|
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.
|
|
|
|
|
|
|
|
- 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```json
|
|
{
|
|
"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
|