{
  "schema": "https://miscsubjects.com/schemas/jarticle.json",
  "status": "published",
  "slug": "write-an-article",
  "title": "How to write an article here",
  "kind": "guide",
  "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"
  ],
  "ontology": {
    "above": [],
    "below": [],
    "adjacent": [
      "json-articles-how-they-work"
    ]
  },
  "body": [
    "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]].\n\n## 1. Create it\n\nSend the object to one address. The key is printed by the command in the header.\n\n```bash\ncurl -sS -X POST https://miscsubjects.com/api/jarticles \\\n  -H \"x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"slug\":\"my-first-article\",\"title\":\"My first article\",\"summary\":\"One sentence.\",\"body\":\"Hello. This is **Markdown**.\"}'\n```\n\nIt answers 201 with the article's hash. A slug that exists answers 409.\n\n## 2. The fields\n\n| Field | What goes in it |\n| --- | --- |\n| slug | The address, /a/<slug>. Lowercase letters, digits, dashes. |\n| title | The headline. |\n| summary | One or two sentences. The lead under the title. |\n| kind | What it is about: person, company, procedure, place, concept. Any word. |\n| status | draft or published. Start with draft. |\n| tags | A list of short words. |\n| facts | The data, nested as deep as needed. Numbers and names live here. |\n| body | Markdown, or a list of blocks. A block is Markdown or a widget. |\n| sources | Where each checkable fact came from: url, title, publisher, the exact quote. |\n\n## 3. The body\n\nWrite 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.\n\nTo draw something other than text, make the body a list and put a widget object in it:\n\n```json\n{\n  \"body\": [\n    \"## Heading\\n\\nA paragraph.\",\n    { \"type\": \"stat\", \"value\": \"42\", \"label\": \"what the number counts\" },\n    { \"type\": \"quote\", \"text\": \"The quotation.\", \"cite\": \"who said it\" },\n    { \"type\": \"note\", \"title\": \"Note\", \"text\": \"Text, in Markdown.\" },\n    { \"type\": \"terminal\", \"lang\": \"bash\", \"code\": \"echo hello\" },\n    { \"type\": \"article\", \"slug\": \"another-article\", \"relation\": \"what it is to this one\" },\n    { \"type\": \"json\", \"title\": \"the data\", \"value\": { \"any\": \"json\" } },\n    \"More Markdown after the widgets.\"\n  ]\n}\n```\n\nEvery 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.\n\n## 4. Change one piece\n\nYou never resend the whole article. Read its hash, then patch the piece:\n\n```bash\ncurl -sS -X PATCH https://miscsubjects.com/api/jarticles/my-first-article \\\n  -H \"x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)\" \\\n  -H \"content-type: application/json\" \\\n  -H \"if-match: <the hash from the read>\" \\\n  -d '{\"ops\":[{\"op\":\"set\",\"path\":\"summary\",\"value\":\"A better sentence.\"},{\"op\":\"append\",\"path\":\"tags\",\"value\":\"example\"}]}'\n```\n\nThe 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.\n\n## 5. The rules\n\n- Plain English. Short sentences. Name every thing by what it is.\n- Data only. No scores, rankings, advice, pitches or recommendations.\n- No invented numbers. A value no source states is the string UNKNOWN.\n- Every fact a reader can check gets a source with the exact quote.\n- Put facts in facts; use prose to explain them. Do not repeat a number in prose that is not in facts.\n- Never call a model through the build to write or test.\n\n## 6. Check it, then publish\n\nRun 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.\n\n## 7. Read any article\n\nEvery 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."
  ],
  "type": "article",
  "created": "2026-10-08T14:43:21.148Z",
  "updated": "2026-10-08T14:43:29.694Z",
  "version": 2,
  "hash": "43b2db6df26363410413071c3cf797f8e1710f3575464c21f5271b1f9e85730a",
  "styling": {
    "scope": "shared",
    "how": "no value on the page is set by hand: each comes from this theme, and each theme value becomes the CSS variable named beside it. PATCH https://miscsubjects.com/api/jarticles/theme changes them.",
    "widget_style": {
      "what": "every widget may carry style: {…}; these are the only keys it reads",
      "rotate": "degrees, a number",
      "offset_x": "pixels, a number",
      "offset_y": "pixels, a number",
      "pulse": "true to pulse"
    },
    "theme": {
      "color": {
        "page_bg": "#f5f5f7",
        "sheet_bg": "#ffffff",
        "ink": "#1d1d1f",
        "soft": "#424245",
        "muted": "#6e6e73",
        "dim": "#86868b",
        "line": "#d2d2d7",
        "accent": "#0071e3",
        "accent_soft": "rgba(0,113,227,0.08)",
        "link": "#0066cc",
        "selection": "rgba(0,113,227,0.18)",
        "widget_bg": "#f5f5f7",
        "widget_border": "#d2d2d7",
        "card_bg": "#ffffff",
        "code_bg": "#f5f5f7",
        "json_bg": "#161b19",
        "json_ink": "#e6e1d4",
        "json_key": "#7fd3c3",
        "json_string": "#e9c46a",
        "json_number": "#f4a261",
        "json_bool": "#c792ea",
        "json_null": "#928d7e",
        "json_punct": "#6b6759",
        "json_bar": "#0e1512",
        "kind_badge_bg": "#0e6e60",
        "kind_badge_ink": "#ffffff"
      },
      "color_dark": {
        "page_bg": "#000000",
        "sheet_bg": "#1d1d1f",
        "ink": "#f5f5f7",
        "soft": "#d2d2d7",
        "muted": "#a1a1a6",
        "dim": "#86868b",
        "line": "#424245",
        "accent": "#2997ff",
        "accent_soft": "rgba(41,151,255,0.12)",
        "link": "#2997ff",
        "selection": "rgba(41,151,255,0.25)",
        "widget_bg": "#2c2c2e",
        "widget_border": "#424245",
        "card_bg": "#1d1d1f",
        "code_bg": "#2c2c2e",
        "json_bg": "#0a0d0c",
        "json_ink": "#e6e1d4",
        "json_key": "#7fd3c3",
        "json_string": "#e9c46a",
        "json_number": "#f4a261",
        "json_bool": "#c792ea",
        "json_null": "#757062",
        "json_punct": "#5d665f",
        "json_bar": "#060807",
        "kind_badge_bg": "#4fc1ab",
        "kind_badge_ink": "#0b0f0d"
      },
      "font": {
        "display": "-apple-system,BlinkMacSystemFont,\"SF Pro Display\",\"SF Pro Text\",\"Helvetica Neue\",Helvetica,Arial,sans-serif",
        "body": "-apple-system,BlinkMacSystemFont,\"SF Pro Display\",\"SF Pro Text\",\"Helvetica Neue\",Helvetica,Arial,sans-serif",
        "mono": "ui-monospace,SFMono-Regular,\"SF Mono\",Menlo,Consolas,monospace",
        "google_fonts": ""
      },
      "size": {
        "body": "17px",
        "small": "17px",
        "eye": "17px",
        "lead": "17px",
        "h1": "52px",
        "h2": "34px",
        "h3": "22px",
        "byline": "17px",
        "h1_measure": "none",
        "code": "17px",
        "json": "17px",
        "widget_title": "17px"
      },
      "leading": {
        "body": "1.7",
        "head": "1.18",
        "lead": "1.5",
        "json": "1.6"
      },
      "weight": {
        "display": "700",
        "head": "700",
        "body": "400",
        "strong": "700",
        "eye": "700"
      },
      "tracking": {
        "eye": "0.14em",
        "display": "-0.03em",
        "body": "-0.006em",
        "badge": "0.08em"
      },
      "layout": {
        "sheet_width": "1000px",
        "text_width": "880px",
        "gutter": "16px",
        "sheet_padding": "56px 64px 64px",
        "sheet_padding_mobile": "24px 18px 40px",
        "sheet_margin": "28px auto 72px",
        "block_gap": "1.15em",
        "widget_gap": "28px",
        "grid_gap": "14px"
      },
      "border": {
        "sheet": "0px solid",
        "sheet_radius": "30px",
        "widget": "1px solid",
        "widget_radius": "24px",
        "card_radius": "24px",
        "badge_radius": "999px",
        "rule": "1px solid",
        "code_radius": "18px",
        "accent_bar": "3px"
      },
      "shadow": {
        "sheet": "0 1px 1px rgba(0,0,0,.02),0 6px 26px rgba(0,0,0,.05)",
        "widget": "none",
        "card_hover": "0 10px 28px -16px rgba(28,27,23,0.35)"
      },
      "motion": {
        "hover": "160ms ease"
      }
    }
  },
  "page": "https://miscsubjects.com/a/write-an-article",
  "json": "https://miscsubjects.com/a/write-an-article.json",
  "markdown": "https://miscsubjects.com/a/write-an-article.md",
  "theme": "https://miscsubjects.com/article-theme.json",
  "calls": [
    {
      "what": "this article as a page (no key)",
      "method": "GET",
      "url": "https://miscsubjects.com/a/write-an-article",
      "headers": {}
    },
    {
      "what": "this article as its object (no key)",
      "method": "GET",
      "url": "https://miscsubjects.com/a/write-an-article.json",
      "headers": {}
    },
    {
      "what": "this article as Markdown (no key)",
      "method": "GET",
      "url": "https://miscsubjects.com/a/write-an-article.md",
      "headers": {}
    },
    {
      "what": "the object with its hash, drafts too",
      "method": "GET",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
      }
    },
    {
      "what": "one piece and that piece’s hash",
      "method": "GET",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article/at?path=facts",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
      }
    },
    {
      "what": "grep: every key or value that matches, with the path to change it",
      "method": "GET",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article/grep?q=owner",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
      }
    },
    {
      "what": "change pieces (set, merge, delete, append, insert, move); if-match is the hash",
      "method": "PATCH",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
        "content-type": "application/json",
        "if-match": "<hash from the read>"
      },
      "body": {
        "ops": [
          {
            "op": "set",
            "path": "facts.example",
            "value": 1
          }
        ]
      }
    },
    {
      "what": "replace the whole object",
      "method": "PUT",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
        "content-type": "application/json",
        "if-match": "<hash>"
      },
      "body": {
        "slug": "write-an-article",
        "title": "…"
      }
    },
    {
      "what": "fetch every source, hash what came back and check the quote is in it",
      "method": "POST",
      "url": "https://miscsubjects.com/api/jarticles/write-an-article/verify",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
        "content-type": "application/json"
      },
      "body": {}
    },
    {
      "what": "an Obsidian-style command",
      "method": "POST",
      "url": "https://miscsubjects.com/api/jarticles/cli",
      "headers": {
        "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
        "content-type": "application/json"
      },
      "body": {
        "command": "backlinks",
        "file": "write-an-article"
      }
    }
  ]
}