/telegraph-publisher

Telegraph Content Format Reference

Node Format

Telegraph API content is a JSON array of Node objects.

A Node is either:

• A string (text content)
• A NodeElement object:

  {
    "tag": "p",
    "attrs": {"href": "https://...", "src": "https://..."},
    "children": ["text", {"tag": "b", "children": ["bold"]}]
  }

Fields

Supported Tags

Size Limit

• Maximum content size: 64 KB (serialized UTF-8 JSON)
• The content_converter.py uses 60 KB threshold for auto-split (4 KB safety margin)

Examples

Simple paragraph

[{"tag": "p", "children": ["Hello, world!"]}]

Formatted text

[{"tag": "p", "children": ["This is ", {"tag": "b", "children": ["bold"]}, " and ", {"tag": "i", "children": ["italic"]}]}]

Image with caption

[{"tag": "figure", "children": [
  {"tag": "img", "attrs": {"src": "https://example.com/photo.jpg"}},
  {"tag": "figcaption", "children": ["Photo description"]}
]}]

YouTube embed

[{"tag": "figure", "children": [
  {"tag": "iframe", "attrs": {"src": "https://www.youtube.com/embed/dQw4w9WgXcQ"}}
]}]

Code block

[{"tag": "pre", "children": [{"tag": "code", "children": ["def hello():\n    print('world')"]}]}]

Complete article

[
  {"tag": "h3", "children": ["Introduction"]},
  {"tag": "p", "children": ["This article covers..."]},
  {"tag": "figure", "children": [
    {"tag": "img", "attrs": {"src": "https://example.com/diagram.png"}},
    {"tag": "figcaption", "children": ["Architecture diagram"]}
  ]},
  {"tag": "h3", "children": ["Details"]},
  {"tag": "p", "children": ["The implementation uses ", {"tag": "code", "children": ["async/await"]}, " pattern."]}
]

HTML to Node Mapping

The content_converter.py script converts HTML fragments to Node JSON:

<h3>Title</h3>              → {"tag": "h3", "children": ["Title"]}
<p>Text <b>bold</b></p>     → {"tag": "p", "children": ["Text ", {"tag": "b", "children": ["bold"]}]}
<img src="url">             → {"tag": "img", "attrs": {"src": "url"}}
<a href="url">link</a>      → {"tag": "a", "attrs": {"href": "url"}, "children": ["link"]}

Unsupported tags (e.g., <div>, <span>, <h1>, <h2>) are stripped — their children are preserved and moved to the parent element.

Table Handling

Telegraph does not support native table nodes.

This skill accepts input HTML tables and converts them to a monospace pre block:

<table>
  <thead>
    <tr><th>Домен</th><th>Расход, руб.</th></tr>
  </thead>
  <tbody>
    <tr><td>metallik.ru</td><td>82 900</td></tr>
    <tr><td>mir-shtaketnika.ru</td><td>38 367</td></tr>
  </tbody>
</table>

becomes a pre node with aligned box-drawing output, for example:

[{
  "tag": "pre",
  "children": ["┌────────────────────┬──────────────┐\n│ Домен              │ Расход, руб. │\n├────────────────────┼──────────────┤\n│ metallik.ru        │ 82 900       │\n│ mir-shtaketnika.ru │ 38 367       │\n└────────────────────┴──────────────┘"]
}]

Recommended usage:

• exact numbers and labels
• short comparison tables
• spend/domain breakdowns

Not recommended:

• wide tables with many columns
• dense financial statements
• anything that should become a chart instead of a table

Mobile note:

• pre tables are desktop-friendly but degrade quickly on narrow mobile screens
• if the table has many columns, long labels, or status text, prefer:
  • a diagram for the visual pattern
  • a bullet/card layout for exact values
  • or a narrowed 2-column table plus a short textual summary

Platform Limitations

No page deletion

Telegraph does not support deleting published pages — neither via API nor via browser. Once published, a page exists permanently at its URL.

Workaround: page recycling. You can overwrite a page's title and content via editPage:

# "Delete" by clearing content
sh scripts/edit_page.sh --path "Old-Page-03-09" --title "." --html "<p>.</p>"

# Later, reuse for new content
sh scripts/edit_page.sh --path "Old-Page-03-09" --title "New Article" --html-file article.html

This is useful for:

• Cleaning up test/draft pages
• Reusing page URLs for updated content
• "Unpublishing" by replacing with minimal content

Note: The original URL slug (e.g., Old-Page-03-09) cannot be changed. Only title and content are editable.

No page URL customization

Page URL paths are auto-generated from the title at creation time. They cannot be changed later, even if you edit the title.

Account token in browser cookies

The API access_token is stored as an httpOnly cookie named tph_token on telegra.ph. This is the same token used by createAccount API. You can extract it from Chrome DevTools → Application → Cookies (see config/README.md).