# SDK: X posts and articles

> Two kinds in X's own model, each a file listed in allyhub.yaml (project.md): an x-post (a post, a thread or a long post) and an x-article.

Source: https://allyhub.com/docs/reference/sdk/x · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

## An X post

An `x-post` is a YAML file (`- { kind: x-post, file: launch/launch.yaml }`). Its fields are POST /2/tweets's own:

```yaml
reply_settings: following # who may reply to each post: following, mentionedUsers, subscribers or verified
posts:
  - text: |
      We shipped dark mode.
    media:
      - file: ./shots.ts#hero # an image's board, a video item, or a picture or video file, from this file's folder
        alt: The dashboard in dark mode.
  - text: Which do you use?
    poll: { options: [Light, Dark], duration_minutes: 1440 }
```

- **A thread** is its posts in order; each after the first is published as a reply to the one before. A post alone is a thread of one. The first post may also `reply` (`in_reply_to_tweet_id`) or quote (`quote_tweet_id`) a post already on X; quoting through the API needs an Enterprise plan. A post may say `made_with_ai` and `paid_partnership`.
- **Length is X's weighted count**, not the characters shown: Latin letters, digits and common punctuation 1; Chinese, Japanese, Korean and most other scripts 2; every emoji 2, whatever it is made of; every link 23, however long. At most 280 a post.
- **A long post** is a post over 280, which an X Premium account publishes up to 25,000. `allyhub.config.ts`'s `x: { premium: true }` says the account is Premium; it also takes videos up to 4 hours and 16 GB. X's timeline folds a long post at "Show more": at most 280 characters, back to a word's end (measured on x.com; `allyhub frames` draws the fold).
- **Plain text.** The API publishes no bold or italics. A link is its address.
- **A post's text as a block (`|`) or in quotes** when it holds ` #` (YAML reads the rest of the line as a comment), starts with `@`, `#` or a quote, or holds `: `. The line break a block ends in is not posted.
- **Media**: up to 4 pictures (JPEG, PNG or WebP, 5 MB each), or 1 GIF (15 MB), or 1 video (MP4 or MOV), never mixed. Alt text up to 1,000 characters. X publishes no picture size, crop or safe area. A video is checked against the widest of what X publishes: 0.5 s to 20 minutes (4 hours with Premium), 8 GB (16 GB), sides 32 px to 1920 on the long side and 1200 on the short, 1:3 to 3:1. X's ways of posting take less: its web upload 1:2.39 to 2.39:1 at 40 frames a second and 25 Mbps, and without Premium 140 seconds and 512 MB; its API's media guide 1280×1024 and 60 frames a second. A 1280×720 or 720×1280 H.264 MP4 at 30 frames a second under 140 seconds suits every way.
- **Another item's made file**: `./shots.ts#hero` is the image `shots`'s board `hero`, made first when the post is rendered; a video item's file is its first version. Its bytes are checked when it is made.

## An X article

An `x-article` is a Markdown file (`- { kind: x-article, file: launch/story.md }`), its title and cover in its front matter, its body in X's blocks alone:

```markdown
---
title: How we built dark mode
cover: ./shots.ts#cover # a picture file or an image's board; or { file, alt }
---

Paragraphs with **bold**, _italic_, ~~strikethrough~~ and [links](https://example.com).

# A heading (X has two: # a Heading, ## a Subheading)

- a list, one level deep

1. or numbered

> A quote.

<br />

!What the picture shows

https://x.com/allyhub/status/1234567890

https://example.com/launch

---

$$
e^{i\pi} + 1 = 0
$$
```

- **Each element is one of X's blocks**: a paragraph, a Heading (`#`) and a Subheading (`##`), lists a level deep, a quote, a picture, GIF or video on a line of its own (its alt text and its caption), a post's address on a line of its own (an embedded post), any other address on a line of its own (a link's card, as X's link preview), `---` (a divider), `$$ … $$` (an equation), a code block or a table (X's Markdown block: 10,000 together, weighted as X counts), and `<br />` alone on a line (an empty line, which X keeps). A third level of heading, a list inside a list, inline code, a picture or an equation inside a line and other HTML are not: each is a problem at its line.
- **A code block or a picture written inside a list item** stands after the list, and the list starts again after it, as X's editor places it.
- **Media** are pictures (JPEG, PNG or WebP, 5 MB each), GIFs (15 MB) and videos (MP4 or MOV); the cover is a picture at 5:2. An image's board (`./shots.ts#chart`) or a video item (`./teaser.ts`) may be one, made first when the article is rendered. X publishes no most for a title or a body.
- **X Premium** writes articles. Through the API an article is drafted and published, and nothing else: it cannot be changed or deleted once published.

## Check, measure and render

`allyhub check` reports what X refuses under `allyhub.x/…`, at its line. `allyhub inspect <post>` gives each post's weighted length beside 280 and 25,000, its links, mentions, hashtags and cashtags, and its media's bytes; `allyhub inspect <article>` its words, its weighted length, its headings, its media, its embedded posts and links' cards, and its code's weight against 10,000. `allyhub frames` draws a post or an article as X shows it once published (a thread as the timeline does, an article in X's column), in Inter in place of X's own face; an embedded post and a link's card are drawn by their address, as their content is X's to fetch.

`allyhub render <post>` writes POST /2/tweets's request for each post (`posts.json`, the media beside it), or each post's text (`--type txt`). `allyhub render <article>` writes POST /2/articles/draft's request (`article.json`, its media beside it with `media.json`). Publishing to X is not built.
