artwist-polyakov/polyakov-claude-skills/telegraph-publisher

telegraph-publisher

Publish content to Telegraph via API with media support. Best for: articles, research reports, documentation, illustrated content.

STOP — Read Before Acting

• DO NOT pass raw markdown — convert to HTML fragment first (Telegraph API accepts Node JSON, the converter accepts HTML)
• DO NOT pass content larger than 64KB without using auto-split — the script handles this automatically
• DO NOT hardcode access tokens — use config/.env
• DO NOT skip account setup before publishing, editing, listing pages, or reading account details — page-view lookup is public

Quick Start

No token?     → sh scripts/create_account.sh --name "Name"
Have token?   → Save to config/.env
Publish page? → sh scripts/create_page.sh --title "Title" --html "<p>Content</p>"
Edit page?    → sh scripts/edit_page.sh --path "Path-03-09" --title "Title" --html "<p>New</p>"
List pages?   → sh scripts/list_pages.sh
Page views?   → sh scripts/page_views.sh --path "Page-Title-03-09"
Account info? → sh scripts/account_info.sh
Permanent media? → sh scripts/github_upload.sh --file hero.webp --page-path page-path

Account & Ownership

Telegraph accounts are API-only (no password/email). Key concepts:

1. create_account.sh generates access_token + one-time auth_url
2. Open auth_url in browser to bind API account to browser session
3. Pages belong to the account whose token was used in createPage
4. After browser binding: pages visible at telegra.ph, editable both via browser and API
5. Use --revoke to rotate token if compromised

See config/README.md for full ownership model.

Compatibility

Scripts are POSIX sh compatible — work in cloud sandboxes (/bin/sh) and locally. Python scripts use stdlib only (html.parser, json, sys).

Config

create_page.sh, edit_page.sh, list_pages.sh, and account_info.sh require TELEGRAPH_ACCESS_TOKEN in config/.env or environment. Creating an account and reading public page-view statistics do not require an existing Telegraph token.

Optional TELEGRAPH_AUTHOR_NAME and TELEGRAPH_AUTHOR_URL in config/.env or the environment provide author defaults. Explicit flags override each field, including empty strings, in create_page.sh and edit_page.sh. With neither a setting nor a flag, these scripts omit the field. These defaults also apply to edits: do not replace a page's different author unintentionally; pass the intended author explicitly. See config/README.md for precedence and account naming.

If the user supplies an author as [Channel Name](https://t.me/channel), pass Channel Name and https://t.me/channel as separate name and URL values. Scripts accept plain values, not Markdown author links.

For permanent media hosting, prefer a separate public GitHub repo + jsDelivr CDN. Reason: Telegraph's unofficial upload endpoint is unstable and should not be the default publishing path.

GitHub Setup (recommended)

The agent should assume this is the default permanent media backend.

Required GitHub config:

GITHUB_TOKEN=ghp_...
GITHUB_ASSETS_REPO=owner/repo
GITHUB_ASSETS_BRANCH=main
GITHUB_ASSETS_BASE_DIR=pages
GITHUB_MANIFESTS_DIR=manifests

Recommended setup:

1. Create a separate public GitHub repo only for Telegraph media
2. Create a fine-grained PAT only for that repo
3. Grant only:

• Contents: Read and write

1. Save token and repo to config/.env

Why this matters:

• permanent asset URLs via jsDelivr
• lower blast radius if token leaks
• no dependency on Telegraph's glitchy upload endpoint
• deterministic cleanup through page manifests

Agent rule:

• if local images/diagrams need permanent hosting and GitHub config exists, use GitHub-backed media workflow by default
• use upload.sh only as a legacy fallback

Content Format

Telegraph API accepts an array of Node objects. This skill converts HTML fragments to Node JSON automatically.

Supported HTML tags (Telegraph API whitelist): a, aside, b, blockquote, br, code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p, pre, s, strong, u, ul, video

Only href and src attributes are preserved. Unsupported tags are stripped (children kept).

Special case:

• input HTML tables (table, thead, tr, th, td) are converted into a monospace pre block
• use this for compact comparisons, domain spend breakdowns, KPI matrices, and similar tabular fragments
• do not force small tables into diagrams unless the user explicitly wants a visual chart instead of exact values

See references/CONTENT_FORMAT.md for Node format details.

Scripts

create_account.sh

sh scripts/create_account.sh --name "Author Name" [--author-url "https://..."]
sh scripts/create_account.sh --revoke  # rotate token

With a nonempty TELEGRAPH_AUTHOR_NAME configured, --name is optional. The public author name is kept in full; the private account label uses its first 32 Unicode characters.

account_info.sh

sh scripts/account_info.sh
sh scripts/account_info.sh --with-auth-url  # include auth_url in output

create_page.sh

# From HTML string
sh scripts/create_page.sh --title "Article" --html "<h3>Hello</h3><p>World</p>"
 
# From HTML file
sh scripts/create_page.sh --title "Article" --html-file article.html
 
# From pre-built Node JSON
sh scripts/create_page.sh --title "Article" --content-file nodes.json
 
# With author info
sh scripts/create_page.sh --title "Article" --html-file a.html --author-name "Name"

Auto-split: If content exceeds 60KB, automatically splits into multiple pages with an index page linking to parts.

edit_page.sh

sh scripts/edit_page.sh --path "Page-Title-03-09" --title "Updated Title" --html "<p>New content</p>"

list_pages.sh

sh scripts/list_pages.sh
sh scripts/list_pages.sh --offset 0 --limit 20

page_views.sh

Get total views or one calendar-period total for any public Telegraph page. No access token is required.

# All-time views
sh scripts/page_views.sh --path "Page-Title-03-09"
 
# Views for a year, month, day, or hour
sh scripts/page_views.sh --path "Page-Title-03-09" --year 2026
sh scripts/page_views.sh --path "Page-Title-03-09" --year 2026 --month 3
sh scripts/page_views.sh --path "Page-Title-03-09" --year 2026 --month 3 --day 9
sh scripts/page_views.sh --path "Page-Title-03-09" --year 2026 --month 3 --day 9 --hour 12

Period filters are hierarchical: month requires year, day requires month, and hour requires day. The command returns one view count for the selected period, not a time series. Telegraph does not document the timezone used for day and hour filters. Use hours 0-23; the live API rejects 24 despite listing it in the API documentation.

github_upload.sh

Upload local media to the GitHub assets repo and update page manifest:

sh scripts/github_upload.sh --file ./hero.webp --page-path my-page-path
sh scripts/github_upload.sh --file ./diagram.png --page-path my-page-path --name diagram-01.png

Output: commit-pinned jsDelivr URL.

Manifest behavior:

• assets go under pages/<telegraph_path>/...
• manifest goes under manifests/<telegraph_path>.json
• manifest stores asset paths and SHAs for later cleanup

github_delete_page_assets.sh

Delete all GitHub-backed assets for a page using its manifest:

sh scripts/github_delete_page_assets.sh --page-path my-page-path

Cleanup rule:

• delete by manifest, not by title guessing
• use Telegraph path as the stable page identifier

upload.sh

Legacy fallback for local image/video upload to Telegraph:

# Best-effort only
URL=$(sh scripts/upload.sh --file /path/to/photo.jpg)
 
# Use in HTML
echo "<figure><img src=\"$URL\"><figcaption>My photo</figcaption></figure>"

Note: Uses unofficial telegra.ph/upload endpoint. Do not treat it as the primary workflow. Best-effort only — may fail behind corporate proxies/VPNs or without any obvious reason.

render_diagram.sh

Render PlantUML/Mermaid diagrams via public servers:

# Get render URL (image on public server)
sh scripts/render_diagram.sh --type plantuml --file arch.puml
 
# Render + upload to GitHub-backed permanent media
sh scripts/render_diagram.sh --type mermaid --file flow.mmd --github-page-path my-page-path --github-name cohort.png
 
# Legacy fallback: render + upload via Telegraph upload
sh scripts/render_diagram.sh --type mermaid --file flow.mmd --upload

Privacy: Diagram source is sent to plantuml.com / mermaid.ink. Do not use for confidential content.

content_converter.py (internal)

# HTML → Node JSON
echo '<p>Hello <b>world</b></p>' | python3 scripts/content_converter.py
 
# Check serialized size (bytes)
cat nodes.json | python3 scripts/content_converter.py --check-size
 
# Split large content
cat nodes.json | python3 scripts/content_converter.py --split --output-dir /tmp/parts

Media Support

Images

Preferred workflow: upload local files to a dedicated public GitHub assets repo and serve them via jsDelivr.

Why GitHub is worth connecting:

• stable permanent URLs for Telegraph pages
• no dependency on Telegraph's glitchy unofficial upload endpoint
• predictable asset structure for cleanup
• easy separation between article content and media storage

Fallback workflow: use upload.sh only when GitHub-backed hosting is unavailable.

Recommended asset lifecycle:

1. If a page contains local media, first create a draft/stub Telegraph page to get its final path
2. Upload images/diagrams to GitHub under pages/<telegraph_path>/... via github_upload.sh
3. Publish final content with jsDelivr URLs
4. Store a manifest for that page with uploaded asset paths and GitHub blob SHAs
5. On page cleanup/removal, run github_delete_page_assets.sh --page-path <telegraph_path>