/telegraph-publisher

name: telegraph-publisher
description: "Publish and manage Telegraph pages with media, page-view statistics, and auto-split for long articles. ALWAYS read SKILL.md before first use."

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](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](config/README.md#author-defaults) 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`

4. 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](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"

| Param | Required | Description | |-------|----------|-------------| | `--title` | yes | Page title (1-256 chars) | | `--html` | one of three | Inline HTML strin