---
slug: write-an-article
title: "How to write an article here"
kind: guide
status: published
hash: 43b2db6df26363410413071c3cf797f8e1710f3575464c21f5271b1f9e85730a
created: 2026-10-08T14:43:21.148Z
updated: 2026-10-08T14:43:29.694Z
summary: "One short page: the call that creates an article, its fields, the body and its widgets, how to change one piece, the rules, and how to publish."
tags: ["json","guide","models"]
above: []
below: []
adjacent: ["[[json-articles-how-they-work]]"]
nested: []
---
# How to write an article here

*One short page: the call that creates an article, its fields, the body and its widgets, how to change one piece, the rules, and how to publish.*

An article is one JSON object. Post it and the site draws the page, the Markdown and the JSON. This page is all a model needs to write one. The full reference, with every widget and every call, is [[json-articles-how-they-work]].

## 1. Create it

Send the object to one address. The key is printed by the command in the header.

```bash
curl -sS -X POST https://miscsubjects.com/api/jarticles \
  -H "x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)" \
  -H "content-type: application/json" \
  -d '{"slug":"my-first-article","title":"My first article","summary":"One sentence.","body":"Hello. This is **Markdown**."}'
```

It answers 201 with the article's hash. A slug that exists answers 409.

## 2. The fields

| Field | What goes in it |
| --- | --- |
| slug | The address, /a/<slug>. Lowercase letters, digits, dashes. |
| title | The headline. |
| summary | One or two sentences. The lead under the title. |
| kind | What it is about: person, company, procedure, place, concept. Any word. |
| status | draft or published. Start with draft. |
| tags | A list of short words. |
| facts | The data, nested as deep as needed. Numbers and names live here. |
| body | Markdown, or a list of blocks. A block is Markdown or a widget. |
| sources | Where each checkable fact came from: url, title, publisher, the exact quote. |

## 3. The body

Write Markdown: headings with ##, lists, tables, **bold**, [links](https://example.com). Link another article by putting its slug between double square brackets. To put another article in as a card, put an exclamation mark and the same brackets alone on a line.

To draw something other than text, make the body a list and put a widget object in it:

```json
{
  "body": [
    "## Heading\n\nA paragraph.",
    { "type": "stat", "value": "42", "label": "what the number counts" },
    { "type": "quote", "text": "The quotation.", "cite": "who said it" },
    { "type": "note", "title": "Note", "text": "Text, in Markdown." },
    { "type": "terminal", "lang": "bash", "code": "echo hello" },
    { "type": "article", "slug": "another-article", "relation": "what it is to this one" },
    { "type": "json", "title": "the data", "value": { "any": "json" } },
    "More Markdown after the widgets."
  ]
}
```

Every other widget (image, gallery, checklist, card, imessage, whatsapp, caveat, thread, the source cards and the social posts) is listed with its JSON, drawn, in the reference.

## 4. Change one piece

You never resend the whole article. Read its hash, then patch the piece:

```bash
curl -sS -X PATCH https://miscsubjects.com/api/jarticles/my-first-article \
  -H "x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)" \
  -H "content-type: application/json" \
  -H "if-match: <the hash from the read>" \
  -d '{"ops":[{"op":"set","path":"summary","value":"A better sentence."},{"op":"append","path":"tags","value":"example"}]}'
```

The operations are set, merge, delete, append, insert and move. A 412 means someone changed the article after you read it: read it again, apply again.

## 5. The rules

- Plain English. Short sentences. Name every thing by what it is.
- Data only. No scores, rankings, advice, pitches or recommendations.
- No invented numbers. A value no source states is the string UNKNOWN.
- Every fact a reader can check gets a source with the exact quote.
- Put facts in facts; use prose to explain them. Do not repeat a number in prose that is not in facts.
- Never call a model through the build to write or test.

## 6. Check it, then publish

Run POST /api/jarticles/<slug>/verify. It fetches each source, hashes the page and checks the quote is in it. Publish only when every quote_found is true: patch status to published.

## 7. Read any article

Every article, of any kind, answers at /a/<slug> (the page), /a/<slug>/json (the whole object) and /a/<slug>/md (the Markdown). The JSON view on a page shows the same text.

---

**adjacent:** [[json-articles-how-they-work]]