Neu in v3New in v3v3.9.0

In v3 ist PullMD von einem reinen Web-Reader zu einem allgemeinen Alles-zu-Markdown-Dienst gewachsen. Alles über die normale Web-Extraktion hinaus ist optional und lässt sich einzeln aktivieren:

In v3, PullMD grew from a web-page reader into a general anything-to-Markdown service. Everything beyond plain web extraction is optional and enabled individually:

• Sauberer Body - der Markdown-Body ist standardmäßig nur noch # Titel + Inhalt; Quell-URL, Datum und Metadaten liegen im YAML-Frontmatter, statt im Text wiederholt zu werden (spart Tokens).
• Dokumente - PDF, Word, PowerPoint, Excel, EPUB u. a. per URL oder Upload (Drag-and-drop in der Web-Oberfläche).
• PDF-Tabellen (OCR) - optionaler, hochwertiger PDF-Pfad mit ?pdf=ocr für saubere Tabellen.
• Bilder & Audio - optionale Bildbeschreibung und Audio-Transkription.
• YouTube - Titel, Beschreibung und Transkript mit klickbaren Timecodes, ohne API-Key.

• Clean body - the Markdown body is now just # Title + content; the source URL, date and metadata live in the YAML frontmatter instead of being repeated in the text (saves tokens).
• Documents - PDF, Word, PowerPoint, Excel, EPUB and more, by URL or upload (drag-and-drop in the web UI).
• PDF tables (OCR) - an optional high-quality PDF path with ?pdf=ocr for clean tables.
• Images & audio - optional image captioning and audio transcription.
• YouTube - title, description and transcript with clickable timecodes, no API key.

Seitdem dazugekommen

Added since

• Hacker News (v3.1) - eigene Pipeline für Items, Kommentar-Permalinks und Listings, mit sauberem verschachteltem Kommentarbaum statt Layout-Tabellen.
• Teilen aus der PWA (v3.1) - Share-Button neben Kopieren übergibt das Markdown an das native Share-Sheet; der Frontmatter-Schalter wirkt sofort, ohne zweiten Pull.
• Transkript-Status (v3.2) - X-Transcript-Status unterscheidet bei YouTube ein fehlendes Transkript von einer temporären Sperre.
• SSRF-Schutz (v3.3) - Anfragen an interne Adressen werden standardmäßig abgelehnt, siehe Endpunkte.
• Query-Extraktion (v3.4) - ?query= liefert nur die zur Frage passenden Abschnitte statt der ganzen Seite, siehe Query-Extraktion.
• Site-Recipes (v3.5/v3.6) - pro Host konfigurierbare Extraktion, inklusive Frontmatter aus JSON-LD und select.content, um den Artikel-Body direkt zu benennen.
• Coverage Guard (v3.7) - erkennt Extraktionen, die nur einen Bruchteil der Seite behalten haben, und holt den fehlenden Teil nach.
• Kontenverwaltung (v3.8) - wer kein Admin ist, kann Einträge aus der eigenen Historie löschen; die Selbstregistrierung lässt sich schließen, und Konten lassen sich per CLI anlegen, siehe Authentifizierung.
• Download-Button (v3.9) - speichert das Ergebnis als .md-Datei; den Dateinamen schlägt der Server vor (X-Suggested-Filename), auf Wunsch mit Datums-Präfix.

• Hacker News (v3.1) - a dedicated pipeline for items, comment permalinks and listings, producing a clean nested comment tree instead of layout-table soup.
• Share from the PWA (v3.1) - a share button next to Copy hands the Markdown to the native share sheet; the frontmatter toggle now applies instantly, with no second pull.
• Transcript status (v3.2) - X-Transcript-Status tells a missing YouTube transcript apart from a temporary block.
• SSRF protection (v3.3) - requests to internal addresses are rejected by default, see Endpoints.
• Query extraction (v3.4) - ?query= returns only the sections relevant to your question instead of the whole page, see Query extraction.
• Site recipes (v3.5/v3.6) - per-host extraction tuning, including frontmatter from JSON-LD and select.content to name the article body outright.
• Coverage guard (v3.7) - detects extractions that kept only a sliver of the page and recovers the rest.
• Account controls (v3.8) - a non-admin can delete entries from their own history, self-registration can be closed, and accounts can be created from the CLI, see Authentication.
• Download button (v3.9) - saves the result as a .md file, named by the server (X-Suggested-Filename), optionally with a date prefix.

Was macht PullMD?What PullMD does/api

PullMD ruft eine beliebige URL ab und liefert sie als sauberes Markdown zurück. Je nach Quelle wird der passende Extraktions-Pfad gewählt:

PullMD fetches any URL and returns it as clean Markdown. It picks the right extraction path depending on the source:

• Reddit — eigene Pipeline für Posts, Kommentare, Subreddit-Listings (mit Tiefe und Limit konfigurierbar).
• Hacker News — eigene Pipeline für Items, Kommentar-Permalinks und Listings (Front/Newest/Ask/Show/Jobs); verschachtelte Kommentare mit konfigurierbarer Tiefe.
• Cloudflare-Markdown — wenn die Quelle Accept: text/markdown nativ unterstützt, wird das direkt durchgereicht (sauberster Output).
• Readability + Trafilatura — für statisches HTML laufen beide Extraktoren; die Ausgabe mit der besseren Qualitätsbewertung gewinnt. Trafilatura ist ein optionaler Sidecar; ohne ihn bleibt es bei Readability.
• Headless Chromium — wenn die statische Extraktion dünn oder nach Layout-Soup aussieht (typisch für SPAs), wird die Seite im Playwright-Sidecar gerendert und danach neu extrahiert. Mit ?render=force bzw. ?render=skip erzwing- oder abschaltbar.
• Dokumente, YouTube, Bilder, Audio — je nach Instanz-Konfiguration; siehe Dateien konvertieren.

• Reddit — dedicated pipeline for posts, comments, subreddit listings (configurable depth and limit).
• Hacker News — dedicated pipeline for items, comment permalinks, and listings (front/newest/ask/show/jobs); nested comments with configurable depth.
• Cloudflare-Markdown — when the source supports Accept: text/markdown natively, that's passed through directly (cleanest output).
• Readability + Trafilatura — static HTML runs through both extractors and the one with the better quality score wins. Trafilatura is an optional sidecar; without it, Readability alone is used.
• Headless Chromium — when static extraction comes out thin or looks like layout soup (typical for SPAs), the page is rendered in the Playwright sidecar and re-extracted. Force or disable it with ?render=force / ?render=skip.
• Documents, YouTube, images, audio — depending on how the instance is configured; see Converting files.

Zwei Korrekturen laufen darüber: Site-Recipes passen die Extraktion pro Host an (siehe Site-Recipes), und der Coverage Guard greift ein, wenn die Extraktion nur einen Bruchteil einer großen Seite behalten hat, und konvertiert stattdessen den Container mit dem eigentlichen Body. Er kann ein Ergebnis nur vergrößern, meldet sich als source: coverage-guard und lässt sich mit PULLMD_COVERAGE_GUARD=off abschalten.

Two corrections sit on top: site recipes tune extraction per host (see Site recipes), and the coverage guard steps in when an extraction kept only a sliver of a large page, converting the container that actually holds the body instead. It can only grow a result, reports itself as source: coverage-guard, and is switched off with PULLMD_COVERAGE_GUARD=off.

Welcher Pfad genommen wurde, sieht man im Response-Header X-Source und in der History neben jedem Eintrag.

Which path was used shows up in the response header X-Source and next to each entry in the history.

Cache & TTLCache & TTLSQLite

Jeder Pull wird in einer SQLite-Datenbank gespeichert. Zwei Zeitspannen sind wichtig:

Every pull is stored in a SQLite database. Two timeouts matter:

So funktioniert /s/:id

How /s/:id behaves

• Cache < 1 h alt → liefert die gespeicherte Version sofort.
• Cache ≥ 1 h alt → ruft die Quelle frisch ab, schreibt zurück, liefert das neue Markdown.
• Quelle nicht erreichbar (404, Netzwerk, …) → liefert den letzten gespeicherten Stand als Snapshot. Keine Stille-Failure-Lücke.
• Cache > 90 Tage ohne Re-Fetch → Eintrag wird beim nächsten Schreibvorgang gelöscht; Share-Link gibt 404 zurück.

• Cache < 1 h old → returns the stored version immediately.
• Cache ≥ 1 h old → re-fetches the source, writes back, serves the new markdown.
• Source unreachable (404, network, …) → falls back to the last stored snapshot. No silent failure.
• Cache > 90 days without a re-fetch → entry is pruned on next write; share link returns 404.

Tipp: Subreddit als Live-Feed

Tip: subreddit as a live feed

Pull einmal einen Subreddit-Listing-Link, merke dir die Share-ID — und ruf danach nur noch /s/:id auf. Nach jeder Stunde löst der nächste Aufruf einen frischen Fetch aus, die Share-ID bleibt stabil, der Inhalt aktualisiert sich. Praktisch für KI-Agenten, die einen festen Endpoint mit regelmäßig aktuellem Inhalt brauchen.

Pull a subreddit-listing URL once, remember the share ID — and from then on only call /s/:id. After each hour the next request triggers a fresh fetch, the share ID stays stable, and the content updates. Handy for AI agents that need a fixed endpoint with regularly refreshed content.

In KI-Agenten einrichtenSet up in AI agentssetup

Option 1 — Universal: Prompt einfügen

Option 1 — Universal: paste a prompt

Funktioniert in jedem Chat-Agent (ChatGPT, Claude.ai, Gemini, Perplexity, …). Kopiere den Block, füge ihn als System- oder Custom-Instruction ein:

Works in any chat-style agent (ChatGPT, Claude.ai, Gemini, Perplexity, …). Copy the block, paste it as a system or custom instruction:

When you need to read a web page, fetch it via PullMD instead of your
built-in fetch/browse tool - not just when that one fails:

  GET https://markdown.invisibletheaters.com}/api?url=<URL>

Returns clean Markdown (text/markdown). Optional query params:

  comments=false        skip Reddit / Hacker News comments
  comment_depth=N       comment nesting depth (default 3)
  frontmatter=true      prepend YAML metadata block
  format=text           strip Markdown, return plain text
  nocache=true          bypass the 1h cache and refetch
  render=force|skip     override the auto headless-Chromium fallback
  extractor=readability|trafilatura|playwright   force one extractor
  pdf=ocr               high-quality PDF conversion (tables)
  query=<text>          got a specific question? pass it and get back only
                        the matching sections (70-95% fewer tokens)
  max_tokens=N          budget for query= (default 600, 64-20000)
  lang=de|en            language for the comments section header

Response headers worth checking:
  X-Source       reddit | hackernews | cloudflare | readability |
                 trafilatura | playwright | recipe-content |
                 coverage-guard | markitdown | youtube | pdf-ocr | ...
  X-Quality      0.0-1.0 extraction confidence
  X-Share-Id     8-hex permalink, openable as /s/<id>
  X-Transcript-Status  youtube only: ok | none | blocked | error
                 (blocked/error = transient, not cached — retry later)

Reddit URLs are auto-detected (incl. redd.it short links and /s/ shares).
Hacker News URLs are auto-detected too — items, comment permalinks, and the
front/newest/ask/show/jobs listings.
Use this whenever you would otherwise fetch raw HTML — the markdown is
much cleaner and saves significant context window space. When you only
need specific information rather than the whole document, pass your
question as query= and get back just the relevant sections.

Option 2 — Claude Code Skill

Option 2 — Claude Code skill

Für Claude Code gibt es eine fertige Skill, die WebFetch automatisch durch PullMD ersetzt (mit Fallback). Lade sie als Zip und entpacke nach ~/.claude/skills/:

For Claude Code there's a ready-made skill that automatically routes WebFetch through PullMD (with fallback). Download the zip and unpack into ~/.claude/skills/:

pullmd.zip herunterladenDownload pullmd.zip

curl -O https://markdown.invisibletheaters.com}/pullmd.zip
mkdir -p ~/.claude/skills
unzip pullmd.zip -d ~/.claude/skills/
# Restart Claude Code; the skill activates on web-reading requests.

Upgrade von vor v3: Die Skill hieß früher web-reader. Das neue Zip ersetzt eine bestehende Installation nicht — erst die alte entfernen (rm -rf ~/.claude/skills/web-reader), sonst sind beide Skills parallel aktiv.

Upgrading from pre-v3: the skill used to be called web-reader. The new zip does not replace an existing install — remove the old one first (rm -rf ~/.claude/skills/web-reader), otherwise both skills stay active side by side.

Option 3 — MCP-Server (remote)

Option 3 — MCP server (remote)

PullMD läuft als remote MCP-Server unter https://markdown.invisibletheaters.com}/mcp (Streamable-HTTP-Transport, stateless). Drei Tools: read_url, get_share, list_recent. Server-seitige Updates erreichen automatisch alle Clients — keine lokale Installation nötig.

PullMD runs as a remote MCP server at https://markdown.invisibletheaters.com}/mcp (Streamable-HTTP transport, stateless). Three tools: read_url, get_share, list_recent. Server-side updates reach every client automatically — no local install needed.

Claude Code — Prompt einfügen, Claude installiert es selbst:

Claude Code — paste this prompt and Claude will install it for you:

Installiere den PullMD MCP-Server in Claude Code (User-Scope):
- Name: pullmd
- Transport: http
- URL: https://markdown.invisibletheaters.com}/mcp

Nutze: claude mcp add --transport http pullmd https://markdown.invisibletheaters.com}/mcp
Danach: claude mcp list zur Verifikation.

Install the PullMD MCP server in Claude Code (user scope):
- Name: pullmd
- Transport: http
- URL: https://markdown.invisibletheaters.com}/mcp

Run: claude mcp add --transport http pullmd https://markdown.invisibletheaters.com}/mcp
Then: claude mcp list to verify.

Claude Code — direkt im Terminal:

Claude Code — directly in the terminal:

claude mcp add --transport http pullmd https://markdown.invisibletheaters.com}/mcp

Claude Desktop / Cursor / andere — JSON-Konfig:

Claude Desktop / Cursor / others — JSON config:

{
  "mcpServers": {
    "pullmd": {
      "type": "http",
      "url": "https://markdown.invisibletheaters.com}/mcp"
    }
  }
}

Sobald registriert, erscheinen die drei Tools nativ im Agent — keine Prompt-Anweisungen nötig, das LLM erkennt sie über ihre Schema-Beschreibungen.

Once registered, the three tools surface natively in the agent — no prompt instructions needed, the LLM picks them up via their schema descriptions.

read_url kennt dieselben Stellschrauben wie die REST-API: comments, comment_depth, comment_limit, frontmatter, lang, nocache, extractor, yt_timecodes, yt_chunk, pdf_ocr (statt pdf=ocr), query und max_tokens. MCP-Antworten haben keine Response-Header; findet die Query-Extraktion nichts, steht stattdessen ein Kommentar im Markdown.

read_url exposes the same knobs as the REST API: comments, comment_depth, comment_limit, frontmatter, lang, nocache, extractor, yt_timecodes, yt_chunk, pdf_ocr (instead of pdf=ocr), query and max_tokens. MCP responses carry no headers; when query extraction finds no match it prepends an in-band comment to the markdown instead.

EndpunkteEndpointshttp

Alles, was die Instanz nach außen anbietet. GET /api ist der Hauptweg, der Rest ist Beiwerk für PWA, Betrieb und Integration.

Everything the instance exposes. GET /api is the main path; the rest supports the PWA, operations, and integration.

Zum Schutz vor Server-Side Request Forgery (SSRF) werden Anfragen an private, loopback-, link-local-, CGNAT- und Cloud-Metadata-Adressen (z. B. 169.254.169.254, 100.100.100.200) standardmäßig abgelehnt - auch wenn eine URL erst per Redirect dorthin führt und auch über IPv6-Übergangsadressen. /api und das MCP-Tool read_url prüfen vorab und antworten mit 403, bevor irgendetwas geholt wird; /api/stream meldet die Ablehnung als error-Event. Selbst-Hoster können mit PULLMD_ALLOWED_HOSTS (kommagetrennte CIDRs und/oder Hostnamen) gezielt interne Ziele freigeben.

To guard against Server-Side Request Forgery (SSRF), requests to private, loopback, link-local, CGNAT and cloud-metadata addresses (e.g. 169.254.169.254, 100.100.100.200) are rejected by default - including when a URL only reaches them via redirect, and including IPv6 transition addressing. /api and the MCP read_url tool check up front and answer 403 before fetching anything; /api/stream surfaces the refusal as an error event. Self-hosters can allow specific internal targets via PULLMD_ALLOWED_HOSTS (comma-separated CIDRs and/or hostnames).

API-ParameterAPI parametersGET /api

Dieselben Parameter gelten für GET /api/stream. Alles, was das erwartete Ergebnis verändert (comment_depth, comment_limit, render, extractor, pdf=ocr, yt_*), umgeht den Cache, damit der neue Wert auch wirklich greift.

The same parameters apply to GET /api/stream. Anything that changes the expected result (comment_depth, comment_limit, render, extractor, pdf=ocr, yt_*) bypasses the cache so the new value actually takes effect.

Response-HeaderResponse headershttp

Jede Antwort von /api trägt mit, wie sie zustande kam. Für Agenten ist das der billigste Weg, die Qualität einer Extraktion zu beurteilen, ohne den Text zu analysieren.

Every /api response carries how it was produced. For agents that is the cheapest way to judge an extraction without analyzing the text.

MCP-Antworten haben keine Header. Dort landen dieselben Angaben im Frontmatter bzw. bei format=json im extract-Objekt.

MCP responses have no headers. There the same data lands in the frontmatter, or in the extract object with format=json.

Query-ExtraktionQuery extraction?query=

Wer eine konkrete Frage an eine lange Seite hat, braucht selten die ganze Seite. ?query= nimmt die Frage in natürlicher Sprache entgegen und liefert nur die passenden Abschnitte - auf langen Seiten typischerweise 70-95 % weniger Tokens. Die ganze Seite lohnt sich dann noch, wenn man sie wirklich komplett braucht: zusammenfassen, übersetzen, archivieren.

When you have a specific question about a long page, you rarely need the whole page. ?query= takes that question in natural language and returns only the matching sections - typically 70-95% fewer tokens on long pages. Fetching the full page still makes sense when you genuinely need all of it: summarizing, translating, archiving.

curl -s "https://markdown.invisibletheaters.com}/api?url=https://example.com/long-article&query=how+does+caching+work&max_tokens=800"

• BM25-Ranking über die Überschriften-Abschnitte des konvertierten Markdowns (bei weniger als zwei Überschriften über Absätze). Keine Netzwerkaufrufe, kein LLM, keine zusätzlichen Kosten.
• max_tokens begrenzt die Ausgabe (Default 600, 64–20000, geschätzt als Zeichen / 4).
• Codeblöcke, Tabellen, Listen und Zitate werden nie zerschnitten - passt ein Teil, bleibt der ganze Block. Lücken zwischen den ausgewählten Stellen markiert ein <!-- … -->.
• Passt nichts, oder ist die Seite ohnehin klein genug, kommt die ganze Seite zurück (im ersten Fall mit confidence: low).
• Extrahiert wird aus der bereits gecachten Vollversion: mehrere Fragen an dieselbe URL kosten innerhalb der Cache-Stunde einen einzigen Abruf.
• Ohne query (oder mit leerem Wert) ist die Antwort byte-identisch zu vorher - keine zusätzlichen Header, keine zusätzlichen Felder.

• BM25 ranking over the heading-based sections of the converted Markdown (paragraph-level for pages with fewer than two headings). No network calls, no LLM, no extra cost.
• max_tokens caps the output (default 600, 64–20000, estimated as chars / 4).
• Code fences, tables, lists and blockquotes are never split - if part of one matches, the whole block is kept. Gaps between selected regions are marked with <!-- … -->.
• If nothing matches, or the page is small enough already, the full page comes back (with confidence: low in the first case).
• Extraction runs on the already-cached full page: several questions against one URL cost a single fetch within the cache hour.
• Without query (or with an empty value) the response is byte-identical to before - no extra headers, no extra fields.

Mit ?frontmatter=true kommen extracted, extract_confidence, sections_selected, original_tokens und returned_tokens dazu; format=json liefert dieselben Werte im extract-Objekt.

With ?frontmatter=true you also get extracted, extract_confidence, sections_selected, original_tokens and returned_tokens; format=json returns the same values in the extract object.

Dateien konvertierenConverting filesPOST /api/html · /api/file

Nicht alles steht als abrufbare URL im Netz. Zwei Upload-Wege decken den Rest ab. Beide landen aus Datenschutzgründen nicht im Cache - kein History-Eintrag, kein Share-Link, keine X-Share-Id.

Not everything lives at a fetchable URL. Two upload paths cover the rest. For privacy, neither is ever cached - no history entry, no share link, no X-Share-Id.

Gespeicherte HTML-Seiten

Saved HTML pages

Bereits gespeicherte Seiten ("Seite speichern unter", SingleFile-Exports) lassen sich direkt konvertieren: die .html-Datei auf die PullMD-Oberfläche ziehen (Desktop) oder den gestrichelten Hinweis unter dem URL-Feld antippen, um eine Datei zu wählen (Desktop + Mobile) - oder per API:

Already-saved pages ("Save Page As", SingleFile exports) can be converted directly: drag-and-drop the .html file onto the PullMD UI (desktop) or tap the dashed hint below the URL field to pick a file (desktop and mobile) - or via the API:

curl -s -X POST --data-binary @page.html \
  -H 'Content-Type: text/html' \
  -H 'X-Filename: page.html' \
  "https://markdown.invisibletheaters.com}/api/html"

Optionale Parameter: url=… (Original-URL - aktiviert Site-Recipes und den verlinkten Header), format=json|text, frontmatter=true, extractor=readability|trafilatura. Statt des Headers X-Filename (URI-encodiert) geht auch ?filename=; der Header hält den Dateinamen aus Access-Logs heraus. Maximal 10 MB. Findet die Extraktion so gut wie keinen Inhalt - typisch für eine gespeicherte JavaScript-App-Hülle - kommt 422 mit der Bitte, stattdessen die Original-URL zu schicken.

Optional parameters: url=… (original URL - enables site recipes and the linked header), format=json|text, frontmatter=true, extractor=readability|trafilatura. Instead of the X-Filename header (URI-encoded) you can use ?filename=; the header keeps the file name out of access logs. Max 10 MB. If extraction finds almost no content - typical for a saved JavaScript app shell - you get a 422 asking for the original URL instead.

Dokumente

Documents

PDF, Word, PowerPoint, Excel, EPUB, ZIP (Inhalt wird aufgelistet), CSV, JSON und XML werden zu Markdown konvertiert. Liegt das Dokument im Netz, reicht die normale API - der Dokumenttyp wird am Content-Type erkannt:

PDF, Word, PowerPoint, Excel, EPUB, ZIP (contents listed), CSV, JSON and XML are converted to Markdown. If the document is online, the regular API is enough - the type is detected from the content type:

curl -s "https://markdown.invisibletheaters.com}/api?url=https://example.com/report.pdf"

Lokale Dateien gehen per Upload - rohe Bytes im Body, Content-Type der Datei, maximal 25 MB. In der Web-Oberfläche funktioniert dafür derselbe Drag-and-drop bzw. die Dateiauswahl:

Local files go through the upload path - raw bytes in the body, the file's content type, max 25 MB. In the web UI the same drag-and-drop and file picker handle it:

curl -s -X POST --data-binary @report.pdf \
  -H 'Content-Type: application/pdf' \
  -H 'X-Filename: report.pdf' \
  "https://markdown.invisibletheaters.com}/api/file"

Optionale Parameter: format=json|text, frontmatter=true, pdf=ocr. Die Dokument-Konvertierung braucht den markitdown-Sidecar; ist er nicht konfiguriert, antworten Dokument-URLs und /api/file mit 502. Ob diese Instanz ihn hat, verrät /api/config.

Optional parameters: format=json|text, frontmatter=true, pdf=ocr. Document conversion needs the markitdown sidecar; without it, document URLs and /api/file return 502. Whether this instance has it is reported by /api/config.

Bilder, Audio, YouTube

Images, audio, YouTube

Bilder und Audio funktionieren über denselben Weg (URL oder Upload). Standardmäßig kommen nur Metadaten zurück - EXIF beim Bild, Track-Infos beim Audio. Hat die Instanz ein Vision- bzw. Speech-to-Text-Modell hinterlegt, kommt eine Bildbeschreibung bzw. ein Transkript dazu; die verwendeten Modelle und der Tokenverbrauch stehen dann im Frontmatter. YouTube-URLs liefern Titel, Beschreibung und Transkript, wenn die Instanz das aktiviert hat.

Images and audio work the same way (URL or upload). By default you only get metadata - EXIF for images, track info for audio. If the instance has a vision or speech-to-text model configured, you also get a caption or a transcript; the models used and the token spend then show up in the frontmatter. YouTube URLs return title, description and transcript when the instance enables it.

Share-LinksShare links/s/:id

Jeder Pull bekommt eine 8-stellige Hex-ID als Share-Link, der den exakten Markdown-Stand zurückliefert. Die ID erscheint im Response-Header X-Share-Id und in der Share-Bar unter dem URL-Feld.

Every pull gets an 8-hex share ID returning the exact markdown snapshot. The ID surfaces in the response header X-Share-Id and in the share bar below the URL field.

• GET /s/:id liefert den Markdown (Content-Type text/markdown).
• Wenn der Eintrag < 1 h alt ist: Sofortantwort aus dem Cache. Sonst: frischer Fetch der Quelle und schreibt zurück.
• Die ID bleibt stabil — Re-Fetch ändert nur Inhalt + created_at, nicht die share_id.
• Damit ist der Share-Link auch ein Live-Endpoint: ein KI-Agent kann ihn als festen URL benutzen und kriegt automatisch frisches Markdown.
• Maximales Alter im Cache: 90 Tage ohne Re-Fetch. Da aber jeder /s/:id-Aufruf nach 1 h einen Re-Fetch auslöst, verlängert sich die Lebensdauer mit jeder Nutzung.
• Ist die Quelle nicht erreichbar, wird der letzte Snapshot zurückgegeben — der Link bleibt also auch bei toten Seiten nutzbar.

• GET /s/:id returns the markdown (Content-Type text/markdown).
• If the row is < 1h old: instant cache response. Otherwise: fresh fetch from the source, written back to cache.
• The ID is stable — refresh only updates content + created_at, not the share_id.
• This makes the share link a live endpoint: an AI agent can pin it as a fixed URL and automatically get refreshed markdown.
• Max age in cache: 90 days without a refresh. But since every /s/:id hit older than 1h triggers a refresh, lifetime extends with usage.
• If the source is unreachable, the last snapshot is returned — so the link keeps working even if the source dies.

FrontmatterFrontmatterYAML

Mit ?frontmatter=true wird vor dem Inhalt ein YAML-Block mit Metadaten eingefügt. Felder mit leerem Wert werden weggelassen:

With ?frontmatter=true a YAML metadata block is prepended to the content. Empty fields are omitted:

---
title: "Why I migrated my side-project from Postgres to SQLite"
url: https://news.ycombinator.com/item?id=42424242
source: readability
fetched: 2026-04-25T13:53:00Z
quality: 0.85
author: kentonv
published: 2026-04-24T18:42:00Z
description: "After two years on managed Postgres..."
language: en
share_id: a3f9c2b7
---

Basis-Felder: title, url, source, fetched, quality, author, published, modified, description, language, image, site, extractor_reason, share_id. Je nach Quelle zusätzlich: subreddit, upvotes (Reddit) · duration, views (YouTube) · image_size, audio_seconds, llm_model, llm_tokens, llm_prompt_tokens, llm_completion_tokens (Media) · pdf_pages (PDF-OCR). MCP-Antworten ergänzen share_url, cached, refreshed, age_ms. Mit PULLMD_FRONTMATTER_FIELDS lässt sich die Auswahl serverseitig einschränken.

Base fields: title, url, source, fetched, quality, author, published, modified, description, language, image, site, extractor_reason, share_id. Depending on the source, additionally: subreddit, upvotes (Reddit) · duration, views (YouTube) · image_size, audio_seconds, llm_model, llm_tokens, llm_prompt_tokens, llm_completion_tokens (media) · pdf_pages (PDF OCR). MCP responses add share_url, cached, refreshed, age_ms. PULLMD_FRONTMATTER_FIELDS can trim the selection server-side.

Bei aktiver Query-Extraktion kommen extracted, extract_confidence, sections_selected, original_tokens und returned_tokens dazu. Site-Recipes können weitere Felder beisteuern, etwa aus dem JSON-LD einer Seite.

With query extraction active, extracted, extract_confidence, sections_selected, original_tokens and returned_tokens are added. Site recipes can contribute further fields, e.g. from a page's JSON-LD.

In der Web-App schaltet der Frontmatter-Regler die Anzeige sofort um - der YAML-Block erscheint oder verschwindet, ohne dass man erneut auf Pull drücken muss.

In the web app the Frontmatter toggle switches the view instantly - the YAML block appears or disappears with no second Pull.

Site-RecipesSite recipesjson

Manche Seiten brauchen Nachhilfe: eine Paywall-Hülle, ein Cookie-Banner mitten im Text, ein Layout, in dem die Automatik den falschen Block für den Artikel hält. Site-Recipes sind kleine JSON-Einträge pro Host, die genau das geradebiegen.

Some sites need a nudge: a paywall wrapper, a cookie banner in the middle of the text, a layout where the automatic pick grabs the wrong block. Site recipes are small per-host JSON entries that straighten exactly that out.

• Rendern erzwingen - Seiten, die ohne JavaScript nichts hergeben, gehen direkt in den Headless-Browser.
• Störendes entfernen (select.remove) - seitenspezifische Banner, Teaser, Skelette.
• Body benennen (select.content) - statt die Automatik raten zu lassen, sagt das Recipe direkt, welche Container den Artikel bilden. Ergebnis trägt source: recipe-content.
• Frontmatter füllen - Felder aus dem JSON-LD der Seite oder per CSS-Selektor, z. B. Bewertung, Adresse oder Preisrahmen.

• Force rendering - pages that are empty without JavaScript go straight to the headless browser.
• Remove noise (select.remove) - site-specific banners, teasers, skeletons.
• Name the body (select.content) - instead of letting the automatic pick guess, the recipe says which containers make up the article. Output carries source: recipe-content.
• Fill frontmatter - fields from the page's JSON-LD or via CSS selectors, e.g. rating, address, or price range.

Ein paar Recipes werden mitgeliefert. Selbst-Hoster legen eigene unter data/site-recipes.json ab oder setzen PULLMD_SITE_RECIPES auf einen Pfad; nach Änderungen muss die Instanz neu starten. Was geladen wurde und was abgelehnt, zeigt GET /api/recipes/status. Wie man ein Recipe schreibt (und beisteuert), steht in SITE-RECIPES.md.

A few recipes ship with PullMD. Self-hosters add their own in data/site-recipes.json or point PULLMD_SITE_RECIPES at a path; the instance needs a restart after changes. GET /api/recipes/status reports what loaded and what was rejected. How to write (and contribute) one is documented in SITE-RECIPES.md.

AuthentifizierungAuthenticationoptional

Standardmäßig ist eine PullMD-Instanz offen. Self-Hoster können das umstellen; welcher Modus hier läuft, steht in /api/config unter authMode.

By default a PullMD instance is open. Self-hosters can change that; the mode in use here is reported by /api/config as authMode.

Ist ein Modus aktiv, brauchen /api, /api/stream, die Upload-Endpunkte, /mcp sowie History und Archiv Zugangsdaten. Öffentlich bleiben die Startseite, diese Hilfeseite, das Skill-Zip und vor allem die Share-Links unter /s/:id - geteilte Inhalte bleiben also teilbar.

With a mode active, /api, /api/stream, the upload endpoints, /mcp, history and archive all need credentials. The start page, this help page, the skill zip and above all the share links at /s/:id stay public - shared content stays shareable.

Drei Wege hinein

Three ways in

• Session-Cookie - der Login im Browser. Die Web-App nutzt ihn automatisch; die Sitzung hält 90 Tage und verlängert sich bei Nutzung.
• API-Key - unter /settings erzeugen und als Authorization: Bearer pmd_… mitschicken. Der Schlüssel wird nur einmal angezeigt, danach liegt serverseitig nur noch sein Hash. Das ist der Weg für curl, Skripte und die Claude-Code-CLI.
• OAuth - für Clients ohne Header-Feld, namentlich Claude Desktop und claude.ai im Web. Der Client entdeckt alles Nötige selbst; man verbindet ihn mit https://markdown.invisibletheaters.com}/mcp und landet beim ersten Klick auf der Login- und Zustimmungsseite dieser Instanz.

• Session cookie - the browser login. The web app uses it automatically; the session lasts 90 days and extends with use.
• API key - create one at /settings and send it as Authorization: Bearer pmd_…. The key is shown once; only its hash is kept server-side. This is the path for curl, scripts and the Claude Code CLI.
• OAuth - for clients without a header field, namely Claude Desktop and claude.ai on the web. The client discovers what it needs on its own; point it at https://markdown.invisibletheaters.com}/mcp and the first click takes you to this instance's login and consent screen.

curl -s -H "Authorization: Bearer pmd_YOURKEY" \
  "https://markdown.invisibletheaters.com}/api?url=https://example.com"

claude mcp add --transport http pullmd https://markdown.invisibletheaters.com}/mcp \
  --header "Authorization: Bearer pmd_YOURKEY"

Fehlen die Zugangsdaten, antwortet die API mit 401; im Browser wird stattdessen zur Login-Seite weitergeleitet und danach zurück zur ursprünglichen Seite.

Without credentials the API answers 401; in the browser you are redirected to the login page and back afterwards.

Benutzerverwaltung

Managing users

Konten verwaltet der Betreiber auf der Kommandozeile der Instanz; eine Oberfläche dafür gibt es nicht. In single-admin stammt der eine Benutzer aus den Server-Einstellungen, in multi-user registrieren sich Benutzer selbst - es sei denn, PULLMD_ALLOW_SIGNUP steht auf false. Dann ist create-user der Weg, trotzdem Konten anzulegen.

Accounts are managed by the operator on the instance's command line; there is no UI for it. In single-admin the single user comes from the server settings, in multi-user users sign up themselves - unless PULLMD_ALLOW_SIGNUP is false. In that case create-user is how accounts still get created.

docker compose exec pullmd node scripts/admin.js list-users
docker compose exec pullmd node scripts/admin.js create-user someone@example.com
docker compose exec pullmd node scripts/admin.js make-admin someone@example.com
docker compose exec pullmd node scripts/admin.js reset-password someone@example.com

• list-users - alle Konten mit ID, E-Mail, Admin-Flag und Anlagedatum.
• create-user <email> - legt ein Konto an und fragt das Passwort interaktiv ab (mindestens 8 Zeichen). Das Konto bekommt keine Admin-Rechte.
• make-admin <email> - befördert ein bestehendes Konto zum Admin. Bewusst ein eigener Schritt.
• reset-password <email> - setzt das Passwort neu und wirft dabei alle offenen Sitzungen des Benutzers weg.

• list-users - every account with id, email, admin flag and creation date.
• create-user <email> - creates an account and prompts for the password interactively (8 characters minimum). The account gets no admin rights.
• make-admin <email> - promotes an existing account to admin. Deliberately a separate step.
• reset-password <email> - sets a new password and drops all of that user's open sessions.

Ohne Docker läuft derselbe Befehl als node scripts/admin.js … im Verzeichnis der Instanz. Wichtig: create-user und reset-password lesen das Passwort von der Standardeingabe, es braucht also docker compose exec oder docker exec -it. Ein docker exec ohne -i hängt die Eingabe nicht an; der Befehl bricht dann mit einer Meldung und Code 2 ab und nennt die funktionierenden Aufrufe. Alternativ lässt sich das Passwort hineinpipen: echo "…" | docker exec -i <container> node scripts/admin.js ….

Without Docker the same command runs as node scripts/admin.js … in the instance's directory. Important: create-user and reset-password read the password from standard input, so use docker compose exec or docker exec -it. A plain docker exec without -i does not attach input; the command then aborts with a message and exit code 2 that names the invocations which do work. You can also pipe the password in: echo "…" | docker exec -i <container> node scripts/admin.js ….

Client-ErkennungClient detectionhistory

Jeder Eintrag in der History kriegt ein Client-Badge — daran sieht man, woher der Pull kam:

Every history entry gets a client badge so you can see where the pull originated:

• Browser — normale Web-UI im Browser-Tab.
• PWA — installierte Progressive Web App (Standalone-Mode, Android/iOS/Desktop).
• Claude — User-Agent enthält „Claude" (z. B. via Skill).
• API — alles andere (curl, Skript, MCP-Wrapper, …).

• Browser — regular web UI in a browser tab.
• PWA — installed Progressive Web App (standalone mode, Android/iOS/desktop).
• Claude — User-Agent contains "Claude" (e.g. via the skill).
• API — anything else (curl, scripts, MCP wrappers, …).