Overview#

markdown-web is the browser-facing service in Markdown Tools. It combines markdown-this for extraction with md-to-telegraph for Telegraph conversion and md-to-epub for ebook export, and exposes the workflows through an HTTP API, a small web interface, and bookmarklets.

What It Does#

The service can:

Extract readable content from public URLs as Markdown.
Accept pasted Markdown, raw HTML, local files, and uploaded documents.
Extract browser-captured HTML when a source needs JavaScript or cannot be reached by the server.
Convert Markdown into Telegraph pages, including long documents split across linked pages.
Show a Telegraph preview before publication and let the user return to edit.
Publish Markdown directly to Telegraph from the web editor.
Export one Markdown document or a bulletin with article cards as an EPUB 3.
Upload PNG, JPEG, and WebP images, optimize them to WebP, and return public URLs suitable for Markdown.
Send an optional Telegraph link notification to Telegram users or channels.
Publish long Markdown briefs as Redis-backed jobs.

The service does not replace the reusable packages. Extraction belongs to markdown-this; Markdown-to-Telegraph conversion and Telegraph API calls belong to md-to-telegraph; web orchestration, uploads, jobs, and Telegram notifications stay here.

Web Interface#

The home page accepts a URL, Markdown, or a file. A selected or dropped file starts processing automatically. Markdown can be edited before conversion, and the draft is kept in the browser while the page remains open.

HTML uploads with .html or .htm extensions are extracted as HTML. Pasted HTML is extracted when it starts with a complete document or a structural fragment (article, body, main, section, or div); Markdown and prose that contain HTML later in the text remain Markdown.

The source action is remembered per browser:

Process extracts or converts the source and opens the result for review.
Publish performs the same preparation and publishes directly to Telegraph.

The preview uses a same-origin frame served by /t/preview-frame. This avoids embedding Telegraph directly, which browsers may reject with an iframe connection error, while keeping the preview isolated from the parent page.

Other browser pages are available from the footer:

/about describes the service and its supported workflows.
/bookmarklets/ provides bookmarklets for rendered-page capture.
/t/published/ lists pages published through the service.
/docs exposes the OpenAPI documentation.
/llms.txt provides a machine-readable description for agents.

HTTP API#

Markdown#

Extract a URL with:

GET /md/{url}

For URLs, raw HTML, Markdown, local files, or browser captures, send a source request to:

POST /md

The response is Markdown text. Browser-supplied HTML should include its original source_url so relative links and images can be normalized against the source document.

Telegraph#

Publish a URL directly:

GET /t/{url}

Publish a URL, Markdown document, raw HTML, or uploaded document:

POST /t

Create or update a preview:

POST /t/preview

The response includes a preview identifier and page URL. Send that identifier back when publishing so the service can update the preview pages instead of creating a second set of pages.

EPUB#

Export a URL, Markdown document, raw HTML, or uploaded document as an EPUB 3:

POST /epub

The endpoint accepts the same source request as POST /md. A Markdown brief with ![card](https://example.com/article) markers becomes a book with the brief and its extracted child articles as navigable chapters. Remote images are embedded in the EPUB, and source URLs remain visible in each chapter.

For a rendered browser capture, use:

POST /t/bookmarklet

Images#

Upload an image with:

POST /images

The service validates the image type, converts it to WebP when possible, and returns a public URL. R2-backed storage is enabled when the R2 environment variables are configured.

Long jobs#

For a long Markdown brief, create a job with:

POST /t/jobs
GET /t/jobs/{job_id}
POST /t/jobs/{job_id}/run

Redis is optional. When REDIS_URL is configured, the job state and staged publishing flow survive individual requests.

Telegram Notifications#

Extracted Markdown may contain a notify_telegram front-matter field with comma-separated user or channel IDs. After publication, the configured Telegram bot sends the Telegraph link to those recipients. The bot must be started by a private user, or added with permission to post in a group or channel.

Telegram is an external service, just like Telegraph. The web package sends notifications through its integration but does not own either service or its content.

Deployment Configuration#

The minimum configuration for URL-to-Telegraph publication is:

TELEGRAPH_API_TOKEN: an existing Telegraph account token.

Optional integrations use:

REDIS_URL for durable publishing jobs.
TELEGRAM_WEB_BOT_TOKEN for notifications.
R2_ACCOUNT_ID, R2_BUCKET_NAME, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and R2_PUBLIC_BASE_URL for image storage.

Run the service locally with:

uv run --package markdown-web markdown-web

Then open http://127.0.0.1:8000/. For API details, use the generated Swagger UI at /docs or ReDoc at /redoc.

Overview

Contents