--- type: page id: writing lang: en canonical: https://tomola.org/writing --- # Write for tomola with your AI Use this guide when your user asks you to prepare a topic or reply for tomola. Produce Markdown, with any image files for topics, then create a draft if your user has connected their account. The short page for people is https://tomola.org/writing. Connection instructions: https://tomola.org/connect.md. ## Writing principles - Write in one original language. tomola supplies translations; authors cannot attach their own alternate-language editions. Preserve the intended language when importing a post. - Publish only the user's own writing or material they have permission to publish. Retain attribution and source links where needed. - Give every image meaningful alt text. For an animated figure, also explain what the motion demonstrates. Avoid flashing and rapid changes of brightness. - The person reviews the draft and publishes from the browser approval screen. AI clients prepare drafts; do not publish or operate the approval screen on the person's behalf. ## Supported Markdown Headings, bold and italic emphasis, links, ordered and unordered lists, tables, footnotes, inline and display math (`$…$` and `$$…$$`, rendered with KaTeX), fenced code blocks, block quotes, collapsible details, managed images and mentions are supported. Use `:::details[Heading]` on its own line and close it with `:::` on its own line. Nest at most two levels, using a longer colon fence outside (for example, four outside and three inside). Use no attributes and no other container names. A malformed container is shown literally and reported as `details_literal`. Use `![description](/media/…)` for an uploaded image. A still and motion pair uses `[![description](still URL)](motion URL)`. A figure plays once when it comes into view, then returns to its still; automatic playback is disabled for readers who request reduced motion. Readers can stop it or choose to play it again. With no JavaScript, a link below the still opens the motion version. Mention a member with `@handle`, using their unique username, not their display name. Mentions in code, links, email addresses and block quotes do not call members. See https://tomola.org/llms.txt for mention and notification rules. Raw HTML, SVG, video and animated PNG are not supported. External images become links rather than embedded images. Convert video and interactive graphics to an informative still (optionally paired with a supported animated figure) and include a link to the original page. Custom scripts, iframes and HTML styling cannot be carried over. ## Limits - Topic body: 100,000 units after NFC normalization; East Asian wide/fullwidth code points count as two, other code points as one. Reply body: 50,000 UTF-16 units. Both also have a UTF-8 limit of 262,144 bytes. Markdown source counts toward these limits. - Displayed images per topic: at most 30. Excess images do not reject the draft or post; they become alt text (which may link to the image). A still/motion pair uses two slots toward this display limit. Upload controls are available only for topics, as described below. Still inputs: JPEG, PNG or WebP. Motion inputs: GIF or animated WebP. - Each uploaded file: at most 10,485,760 bytes. A still input: at most 40,000,000 pixels. Stored images are resized to a longest edge of at most 2,000 pixels and rewritten as WebP with embedded metadata removed. Each stored still: at most 2,097,152 bytes. - Motion input: at most 4,096 × 4,096 pixels per frame, 600 frames, 60 seconds and 240,000,000 total decoded pixels (width × height × frames). Each stored motion version: at most 4,194,304 bytes, separately from its still poster. Files exceeding a processing or storage limit may be refused even below the other limits. ## Examples The managed image URLs below are invented examples of the required shape. Replace them with the URLs returned by the image upload API or the writing screen after upload. ### Headings, emphasis and links ````markdown ## An observation **Evidence** differs from *inference*. [Source](https://example.org/article). ```` ### Lists and quotations ````markdown - first - second - third > A quoted observation. > Another sentence. 1. First step 2. Next step ```` ### Tables ````markdown | Observation | Explanation | | --- | --- | | A | B | | C | D | ```` ### Code ````markdown ```python values = [1, 2, 3] print(sum(values)) ``` ```` ### Footnotes and math ````markdown An observation[^source] with $x^2$. $$ \frac{x}{1 + y} = z $$ [^source]: Read the source and check its conditions. ```` ### Collapsible details ````markdown ::::details[**Supplement** and $x^2$] Write experimental settings or a proof here. :::details[Conditions] Use one more colon on the outside when nesting, up to two levels. ::: :::: ```` ### Still image ````markdown ![A diagram showing three connected stages.](/media/0000000000000000000000000000000000000000000000000000000000000000-800x450.webp) ```` ### Still and motion pair ````markdown [![Three stages light up in sequence to show how a signal travels.](/media/0000000000000000000000000000000000000000000000000000000000000000-800x450.webp)](/media/1111111111111111111111111111111111111111111111111111111111111111-800x450.webp) ```` ### Mention ````markdown @example What conditions would change this conclusion? ```` ## Import from another blog or HTML | Source | tomola version | | --- | --- | | KaTeX or MathJax output | Recover the original TeX and put it between inline or display math delimiters. Do not copy rendered HTML. | | HTML details/summary | Use a details container with its summary as the heading; keep nesting within two levels. | | Footnotes and back links | Use Markdown footnote references and definitions. | | Figure and caption | Use an uploaded image with alt text, followed by the caption as a paragraph. | | Animated figure | Upload a supported file and use the still/motion pair. | | Interactive figure or video | Use an informative still, optionally a supported motion pair, and a link to the original page. | | Table of contents, navigation, page decorations | Omit them. Keep the article's own headings and content. | | Relative links to other source pages | Resolve them to absolute URLs at the original site. | Check the original TeX, captions, attribution, footnotes and links after conversion; a screenshot cannot replace missing mathematical source. ## Deliver the draft ### By hand Open https://tomola.org/t/new, switch to Markdown mode and paste the prepared Markdown. Upload image files as described below, check the preview and the selected original language, then let the author review and publish. The same image insertion works when editing a topic. ### With an AI connection or script For MCP, follow https://tomola.org/connect.md to connect the member account with draft permission. Use `tomola_draft_create` with `kind: "topic"`, optional `title`, `body` (Markdown) and `lang`. Replies use `kind: "reply"`, `threadId` and optional `parentId`. Give each intended draft a unique `requestId` and repeat the same arguments on retry. Before every revision, call `tomola_draft_get` with its `id`, read the current body and preserve the author's image Markdown and edits. Send the revised body with `tomola_draft_update`, the same `id`, and `expectedVersion` from the read. These tools can access only drafts owned by that authenticated client. Give the author the returned `approvalUrl`. Use `tomola_draft_status` to check whether they published or discarded the draft. For HTTP, send `POST https://tomola.org/api/drafts` with a draft Bearer token and `Content-Type: text/markdown`; the body is Markdown with optional YAML frontmatter (for example `type: topic`, `title` and `lang`). A reply needs `reply_to: p-` or `reply_to: c-`. The response returns `approve_url`. This API creates drafts only; to revise one, have the author reopen it in the browser, read its current body and apply changes to that body, preserving images and edits. Token setup, request examples, optional fields and errors: https://tomola.org/help/ai.md. Schema: https://tomola.org/api/openapi.json. Keep tokens out of the post and conversation. ### Read the draft diagnostics Draft responses include non-blocking issues: unknown_mention (unresolved or beyond the notification quota), image_not_rendered, link_removed, unicode_review, lang_mismatch and details_literal (unsupported name, missing closing line, attributes or nesting deeper than two levels; optional detailsReason identifies the reason). Each issue has kind, location ({ field: "title" } or { field: "body", line: <1-based line> }), excerpt (at most 80 Unicode code points) and a short English message. At most 50 issues are returned; MCP issuesTruncated (HTTP issues_truncated) says whether more were omitted. When issues exist, MCP issuesNotice (HTTP issues_notice) explains that they do not block publication: revise with tomola_draft_update if unintended, ask your member if unsure, and have your member review the browser approval screen before publishing. HTTP clients can submit a revised draft; there is no HTTP update endpoint. No content-quality or writing-style judgment is made. On creation, an explicit lang is retained. When omitted, the same prose detector as the browser chooses an enabled language; inconclusive or disabled detections use the member's defaultPostLang (main language, then first enabled reading language, then site default). The response includes lang and language: { source: "explicit" | "detected" | "default", detected: }. MCP update without lang preserves the saved language; a mismatch is reported as an issue. MCP create, update and get include issues, issuesTruncated and optional issuesNotice; HTTP creation uses issues, issues_truncated and optional issues_notice. If diagnostics fail, the draft is still returned or saved with an empty issues array and issuesUnavailable: true (HTTP issues_unavailable: true); this is not a clean check. MCP busy diagnostics also signal HTTP 503 with Retry-After, while retaining the successful draft payload; check the result before retrying creation. MCP errors include the error code and its repair message. MCP list stays unchanged. The language decision is returned on creation only and is not stored as draft history. ### Images for topics Images are supported only in topics, not replies. Replies have no image-upload control; prepare text replies and put any needed figures in a topic or link to them. ### Prepare figures for reading - **Display width.** On wide screens, the reading column is about 650 CSS px for English and similar languages, and about 700 CSS px for Japanese, Chinese, and Korean. A wider image placed alone in its own paragraph can extend to about 765 CSS px and shrinks on narrower screens; put the caption in the next paragraph. On phones they fit the reading column, typically about 340–360 CSS px. Figures have no click-to-enlarge control, so make them readable at these sizes. - **Label size.** Aim for a font size of at least 14 CSS px when the figure is displayed at about 700 CSS px wide. For an export W px wide, use a font size of at least W × 14 ÷ 700 px (32 px for a 1,600 px export). On phones, text will be about half as large. Split a dense figure into several figures or move some text into the article or caption. - **Export format and size.** Use PNG for diagrams and other figures with fine lines or text, and JPEG or WebP for photos. Aim for a width of 1,400–2,000 px, about twice the display width. tomola resizes still images to a longest edge of at most 2,000 px and stores them as WebP, so larger exports add no resolution to the stored image. - **Editable source.** If the original Figma file, Keynote deck, or notebook is public, add a regular link to it in the caption or at the end of the article. Embedding it would make readers' browsers contact an external site, let later edits change the published figure, and bypass translation of text inside the figure. ### Upload images before writing a draft With your user's permission, send one local image to POST https://tomola.org/api/media. Use a draft token created at https://tomola.org/settings/tokens with “Upload images” explicitly selected, or an OAuth access token with the separately granted media scope (resource https://tomola.org/mcp). For OAuth, request media in addition to draft only when image uploads are needed; the member explicitly selects “Upload images” at consent. Existing read/draft credentials do not gain this permission. A client registered without media will receive invalid_scope if it requests media; reconnect and register the client again with media included. Cookies and URL tokens are ignored. Uploads use account storage and upload allowances and do not publish anything. Send the image bytes with Content-Type: application/octet-stream (or image/*), or multipart/form-data with exactly one file part (for example, image). Maximum image size: 10485760 bytes. Multipart headers are limited to 8192 bytes and 16 lines. The image is identified and rewritten from its contents; its original filename is not stored. Example: curl -X POST 'https://tomola.org/api/media' -H 'Authorization: Bearer ' -H 'Content-Type: application/octet-stream' --data-binary @diagram.png 201 returns JSON: { mediaId, url, width, height, posterUrl?, posterWidth?, posterHeight?, markdown }. URLs are site-relative. A motion image returns both the animated URL and its still poster URL. The markdown field is a starting example: replace “Describe the image” with a useful description. Still: ![description](url). Motion: [![description](posterUrl)](url). Use those URLs in the body of a draft, created through POST /api/drafts (a draft PAT) or tomola_draft_create (OAuth draft scope). Give your user the returned approvalUrl (REST also calls it approve_url) to review and publish in the browser. A draft-only image remains readable only by its owner. MCP does not import image URLs; this endpoint receives files only. The shared member allowance is 30 images/hour across browser and API; API uploads additionally have 20/hour per member across all credentials. A motion/still pair costs two. Failed attempts count; receive/decoder admission refusals do not. Storage limits: 300 images/member, 104857600 bytes/member and 10737418240 bytes/site. Errors use { error, message }: unauthorized (401), forbidden (403, missing permission or unavailable writing), too_large (413), type or generic (400), rate (429, Retry-After and X-RateLimit-*), quota/member_bytes/site_bytes (409), busy (503, Retry-After). Other processing failures may return generic with 408 or 500. Re-uploading the same image returns the same result while that stored image remains active. ### When your AI cannot upload images If you cannot send image files, for example from a chat-only AI, give your user the image files and their alt text. Images can also be uploaded on topic writing screens: a new topic, a topic draft or a topic edit. After creating a topic draft, have them open its approval URL in the browser and upload the files there. Do not invent an upload endpoint or put external image URLs in place of managed images. On https://tomola.org/t/new, a topic draft's writing screen or a topic edit screen, use the image insertion button to choose one file at a time (or paste an image or drop a file onto the editor). The editor uploads it and inserts managed image Markdown at the cursor. A GIF or animated WebP upload creates a still poster and a motion version, inserting the linked pair. The poster is selected from a frame with content, not necessarily the first frame; the author can replace it with another uploaded still in the Markdown. Replace the default alt text with a description of the figure and, for motion, what the changes show. Keep the returned URLs; do not construct media IDs yourself. Before revising a draft after the author adds images or edits in the browser, call `tomola_draft_get` with its `id` and build the revision from the current body, preserving image Markdown, alt text and the author's changes. Send the revised body with `tomola_draft_update` and set `expectedVersion` to the version you read. If the version changed, read the draft again before proposing a revision. For HTTP-created drafts, have the author reopen the current draft in the browser and revise that body there.