From e84035b21dc95ec10955bdfe850b0fa83e310de2 Mon Sep 17 00:00:00 2001 From: Patrick Schiller Date: Wed, 12 Aug 2026 23:57:41 +0200 Subject: [PATCH] Unify English and German README documentation Signed-off-by: Patrick Schiller --- README.de.md | 282 ++++++++++++++++++++++++++++++++++++--------------- README.md | 19 ++-- 2 files changed, 214 insertions(+), 87 deletions(-) diff --git a/README.de.md b/README.de.md index 7b6a50d..10e615a 100644 --- a/README.de.md +++ b/README.de.md @@ -6,30 +6,47 @@ ![SourceBraid — Weave the web into Markdown.](assets/branding/sourcebraid-social-card.png) -[SourceBraid](https://sourcebraid.com) speichert Artikel, wissenschaftliche Veröffentlichungen, Wiki-Seiten, GitHub Gists und PDF-Dokumente als dauerhaft lesbares Markdown in einem privaten GitHub-Repository. Metadaten landen im YAML-Frontmatter, relevante Bilder als lokale Repository-Assets und alle Einträge zusätzlich in einem durchsuchbaren Index. +[SourceBraid](https://sourcebraid.com) speichert Artikel, wissenschaftliche +Veröffentlichungen, Wiki-Seiten, GitHub Gists und PDF-Dokumente als dauerhaft +lesbares Markdown in einem privaten GitHub-Repository. Metadaten stehen im +YAML-Frontmatter, relevante Bilder werden als lokale Repository-Assets +gespeichert und jede Quelle wird in einen durchsuchbaren Index aufgenommen. + +SourceBraid setzt nicht bloß Lesezeichen für URLs. Es bereitet jede Quelle auf +Grundlage der aussagekräftigsten verfügbaren und vertrauenswürdigen Darstellung +auf, bewahrt ihre Provenienz und hinterlässt ganz normale Dateien samt +Git-Historie, die auch ohne SourceBraid nützlich bleiben. ## So funktioniert SourceBraid -SourceBraid besteht aus Capture-Clients, dem GitHub-Repository als dauerhafter Datenquelle und einem universellen ChatGPT-/Codex-Plugin für Suche und Verwaltung. Es gibt keinen zentralen SourceBraid-Server: Die Chrome-Erweiterung beziehungsweise die iOS-App liest die Quelle, bereitet sie auf und schreibt das Ergebnis direkt in das konfigurierte Repository. Der lokale SQLite-Index ist nur ein jederzeit neu aufbaubarer Such-Cache; maßgeblich bleiben immer die Markdown-Dateien und die Git-Historie auf GitHub. +SourceBraid verbindet Capture-Clients, ein privates GitHub-Repository als +dauerhaft maßgebliche Datenquelle und ein universelles ChatGPT-/Codex-Plugin für +Abruf und Archivverwaltung. Es gibt keinen zentralen +SourceBraid-Inhaltsserver. Die Chrome-Erweiterung beziehungsweise die iOS-App +liest die ausgewählte Quelle, bereitet sie auf und schreibt das Ergebnis direkt +in das konfigurierte Repository. + +Der lokale SQLite-Index ist nur ein jederzeit neu aufbaubarer Such-Cache. +Maßgeblich bleiben die Markdown-Dateien und die Git-Historie. ```mermaid flowchart TD - A["Webseite, Wiki, Gist, arXiv oder PDF"] --> B{"Capture-Client"} + A["Webseite, Wiki, Gist, arXiv-Paper oder PDF"] --> B{"Capture-Client"} B -->|Chrome| C["Browser-Erweiterung"] B -->|iOS| D["App und Share Extension"] - C --> E["Passenden Extraktionsadapter wählen"] + C --> E["Besten Extraktionsadapter wählen"] D --> E E --> F["Inhalt normalisieren, Frontmatter erzeugen und Bilder übernehmen"] F --> G{"PDF-Konvertierung erforderlich?"} - G -->|Nein| H["Markdown, Assets und URL-Hash-Shard speichern"] + G -->|Nein| H["Markdown, Assets und URL-Hash-Metadaten-Shard speichern"] G -->|Ja| I["PDF, Platzhalter und Metadaten speichern"] I --> J["GitHub Action konvertiert mit Docling"] J --> H - H --> K["Privates GitHub-Repository als Source of Truth"] + H --> K["Privates GitHub-Repository als maßgebliche Datenquelle"] K --> L{"Lokaler Suchindex vorhanden?"} L -->|Nein| M["Einmaliger Index-Build"] L -->|Ja| N["Remote-Head und Git-Blob-SHAs vergleichen"] - N -->|Geändert| O["Nur geänderte oder neue Dateien laden"] + N -->|Geändert| O["Nur geänderte oder neue Dateien herunterladen"] N -->|Unverändert| P["Vorhandenen Index verwenden"] M --> Q["SQLite-Index mit FTS5"] O --> Q @@ -39,36 +56,60 @@ flowchart TD Der Ablauf im Einzelnen: -1. **Erfassen:** Eine Person startet SourceBraid auf der geöffneten Seite oder teilt einen Inhalt aus iOS. Tags und eigene Notizen können bereits beim Speichern ergänzt werden. -2. **Extrahieren:** SourceBraid wählt den hochwertigsten verfügbaren Adapter. Strukturierte Quellen wie arXiv, Azure DevOps, Gists oder native Markdown-Endpunkte haben Vorrang vor der allgemeinen DOM-Auslese. -3. **Aufbereiten:** Der Inhalt wird in portables Markdown umgewandelt. SourceBraid ergänzt YAML-Frontmatter, macht relative Quell-Links eindeutig und speichert relevante Bilder neben dem Dokument, damit der Clip auch ohne die ursprüngliche Webseite lesbar bleibt. -4. **Versioniert speichern:** Dokument, Assets und Metadateneintrag werden über die GitHub Contents API geschrieben. Der Metadateneintrag landet anhand des URL-Hashes in einem von bis zu 256 JSONL-Shards. Git-Commits machen jede Änderung nachvollziehbar und wiederherstellbar. -5. **PDFs nachbearbeiten:** Falls keine geeignete HTML-Fassung existiert, bleibt das Original-PDF im Repository. Eine GitHub Action erzeugt mit Docling das endgültige Markdown, extrahiert Abbildungen und ersetzt den zunächst angelegten Platzhalter. -6. **Indexieren:** Beim ersten Einsatz baut das Codex-Plugin aus dem Repository einen lokalen SQLite-FTS5-Index auf. Spätere Aktualisierungen vergleichen den gespeicherten Commit und die Git-Blob-SHAs; dadurch werden nur neue, geänderte oder gelöschte Dateien verarbeitet. -7. **Verwenden:** ChatGPT oder Codex durchsucht normalerweise den lokalen Index, kann Treffer vollständig abrufen und unterstützt eine abgesicherte Löschung mit Vorschau und ausdrücklicher Bestätigung. Ist GitHub vorübergehend nicht erreichbar, bleibt der zuletzt synchronisierte Index lesbar. - -Die Trennung zwischen GitHub-Archiv und lokalem Such-Cache ist für größere Sammlungen entscheidend: Auch bei vielen Tausend Dokumenten muss eine normale Suche nicht alle Markdown-Dateien nacheinander öffnen. Ein vollständiger Durchlauf ist nur für den ersten Aufbau, einen ausdrücklich angeforderten Rebuild oder eine Reparatur nach beschädigtem Index nötig. - -## Unterstützte Formate und Konvertierung - -| Quelle oder Format | Bevorzugte Extraktion | Ergebnis in Markdown | Bilder und Anlagen | Fallback | +1. **Erfassen:** Eine Person startet SourceBraid auf der geöffneten Seite oder + teilt einen Inhalt aus iOS. Tags und eigene Notizen können bereits beim + Speichern ergänzt werden. +2. **Extrahieren:** SourceBraid wählt den hochwertigsten verfügbaren Adapter. + Strukturierte Quellen wie arXiv, Azure DevOps, Gists oder native + Markdown-Endpunkte haben Vorrang vor der allgemeinen DOM-Auslese. +3. **Aufbereiten:** Der Inhalt wird in portables Markdown umgewandelt. + SourceBraid ergänzt YAML-Frontmatter, löst relative Links auf und speichert + relevante Bilder neben dem Dokument, damit der Clip auch ohne die + ursprüngliche Webseite lesbar bleibt. +4. **Versioniert speichern:** Dokument, Assets und Metadateneintrag werden über + die GitHub Contents API geschrieben. Der Metadateneintrag landet anhand des + URL-Hashes in einem von bis zu 256 JSONL-Shards. Normale Git-Commits machen + jede Änderung nachvollziehbar und wiederherstellbar. +5. **PDFs nachbearbeiten:** Falls keine geeignete HTML-Fassung existiert, bleibt + das Original-PDF im Repository. Eine GitHub Action erzeugt mit Docling das + endgültige Markdown, extrahiert Abbildungen und ersetzt den zunächst + angelegten Platzhalter. +6. **Indexieren:** Beim ersten Einsatz baut das Plugin aus dem Repository einen + lokalen SQLite-FTS5-Index auf. Spätere Aktualisierungen vergleichen den + gespeicherten Commit und die Git-Blob-SHAs; dadurch werden nur neue, + geänderte oder gelöschte Dateien verarbeitet. +7. **Verwenden:** ChatGPT oder Codex durchsucht normalerweise den lokalen Index, + kann Treffer vollständig abrufen und unterstützt eine abgesicherte Löschung + mit Vorschau und eindeutiger Bestätigung. Ist GitHub vorübergehend nicht + erreichbar, bleibt der zuletzt synchronisierte Index lesbar. + +Die Trennung zwischen GitHub-Archiv und lokalem Such-Cache ist für größere +Sammlungen entscheidend: Auch bei vielen Tausend Dokumenten muss eine normale +Suche nicht alle Markdown-Dateien nacheinander öffnen. Ein vollständiger +Durchlauf ist nur für den ersten Aufbau, einen ausdrücklich angeforderten +Rebuild oder eine Indexreparatur nötig. + +## Unterstützte Quellen und Konvertierung + +| Quelle oder Format | Bevorzugte Extraktion | Ergebnis in Markdown | Bilder und Anhänge | Fallback | | --- | --- | --- | --- | --- | -| **arXiv-Paper** | Experimentelle arXiv-HTML-Version des vollständigen Papers | Gliederung, Fließtext, Tabellen, Zitate und LaTeX-Formeln; Autoren, arXiv-ID/-Version, DOI, Fachgebiete und Journalreferenz im Frontmatter | Abbildungen werden in den Asset-Ordner kopiert und relativ verlinkt | Wenn kein arXiv-HTML verfügbar ist: PDF im Hintergrund laden und mit Docling konvertieren | -| **PDF über HTTP(S) oder lokale Datei** | Original-PDF plus asynchroner Docling-Workflow in GitHub Actions | Lesereihenfolge, Tabellen, OCR-Text und referenzierte Abbildungen; zunächst Status `pending`, danach fertiges Markdown | Original bleibt als `source.pdf` erhalten; extrahierte Abbildungen liegen daneben | Lokale PDFs benötigen in Chrome **Zugriff auf Datei-URLs zulassen**; passwortgeschützte oder nur per angemeldeter Web-Sitzung erreichbare PDFs werden nicht unterstützt | -| **Azure DevOps Wiki** | Authentifizierte Wiki-REST-API liefert das Quell-Markdown | Azure-Makros werden bereinigt, Mermaid bleibt als `mermaid`-Codeblock erhalten, interne Wiki-Links werden absolut | Geschützte Attachments werden über den noch geöffneten, angemeldeten Tab geladen und lokal abgelegt | Gerenderter `.markdown-content`-Bereich, falls die API nicht erreichbar ist | -| **GitHub Gist** | GitHub Gist API, bei privaten Gists mit dem konfigurierten Token | Einzelne Markdown-Datei direkt; mehrere Dateien als Abschnitte; Quellcode in sprachlich markierten Codeblöcken | Öffentliche Bilder direkt, geschützte GitHub-Bilder über den angemeldeten Gist-Tab | Die Revision einer revisionsspezifischen URL bleibt erhalten | +| **arXiv-Paper** | Experimentelle arXiv-HTML-Version des vollständigen Papers | Gliederung, Fließtext, Tabellen, Zitate und LaTeX-Formeln; Autoren, arXiv-ID/-Version, DOI, Fachgebiete und Journalreferenz im Frontmatter | Abbildungen werden in den Asset-Ordner kopiert und relativ verlinkt | PDF herunterladen und mit Docling konvertieren | +| **PDF über HTTP(S) oder lokale Datei** | Original-PDF plus asynchroner Docling-Workflow in GitHub Actions | Lesereihenfolge, Tabellen, OCR-Text und referenzierte Abbildungen; zunächst Status `pending`, danach fertiges Markdown | Original bleibt als `source.pdf` erhalten; extrahierte Abbildungen liegen daneben | Lokale PDFs benötigen in Chrome **Zugriff auf Datei-URLs zulassen**; verschlüsselte oder sitzungsgebundene PDFs werden nicht unterstützt | +| **Azure DevOps Wiki** | Authentifizierte Wiki-REST-API liefert das Quell-Markdown | Azure-Makros werden normalisiert, Mermaid bleibt als `mermaid`-Codeblock erhalten, interne Wiki-Links werden absolut | Geschützte Anhänge werden über den weiterhin authentifizierten Quell-Tab geladen und lokal abgelegt | Gerenderter `.markdown-content`-Bereich, falls die API nicht erreichbar ist | +| **GitHub Gist** | GitHub Gist API, bei privaten Gists mit dem konfigurierten Token | Einzelne Markdown-Datei direkt; mehrere Dateien als Abschnitte; Quellcode in Codeblöcken mit Sprachkennung | Öffentliche Bilder direkt, geschützte GitHub-Bilder über den Gist-Tab mit aktiver GitHub-Sitzung | Die Revision einer revisionsspezifischen URL bleibt erhalten | | **Natives Markdown** | HTTP-Antwort auf `Accept: text/markdown`, z. B. bei Hashnode oder entsprechend konfigurierten Cloudflare-Seiten | Quell-Frontmatter und doppeltes H1 werden entfernt; relative Links werden absolut | Relevante Bilder werden lokal gespeichert und relativ verlinkt | Danach greifen die spezifischen APIs oder die DOM-Extraktion | | **WordPress** | WordPress-REST-Endpunkt aus den Seitenmetadaten | Artikelinhalt wird aus der strukturierten API-Antwort konvertiert | Relevante Artikelbilder werden lokal gespeichert | Sichtbarer Seiteninhalt | -| **Forem / DEV** | Forem API mit Quell-Markdown | Markdown wird normalisiert und ohne Seiten-Chrome gespeichert | Relevante Bilder werden lokal gespeichert | Sichtbarer Seiteninhalt | +| **Forem / DEV** | Forem API mit Quell-Markdown | Markdown wird normalisiert und ohne Oberflächenelemente der Website gespeichert | Relevante Bilder werden lokal gespeichert | Sichtbarer Seiteninhalt | | **Ghost** | Konfigurierte Ghost Content API | Strukturierter Post-Inhalt; die kanonische URL wird vor der Übernahme geprüft | Relevante Bilder werden lokal gespeichert | Sichtbarer Seiteninhalt | | **Blogger** | Blogger API anhand erkannter Blog- und Post-IDs | Strukturierter Artikelinhalt | Relevante Bilder werden lokal gespeichert | Sichtbarer Seiteninhalt | | **Google-DeepMind-Blog** | Artikelsektionen aus dem Seiten-DOM | Vollständiger Beitrag ohne Cover-Bedienelemente und Karten verwandter Beiträge | Artikelbilder werden lokal gespeichert | Allgemeine Extraktion des sichtbaren Seiteninhalts | | **JSON Feed, RSS oder Atom** | Im HTML angekündigter Feed | Vollständiger Feed-Inhalt, sofern vorhanden | Relevante Bilder werden lokal gespeichert | Sichtbarer Seiteninhalt | -| **Allgemeine HTML-Seite** | Sichtbarer DOM, bevorzugt `article`, `main` oder `[role="main"]` | Überschriften, Absätze, Links, Listen, Zitate, Codeblöcke und Tabellen | Inhaltlich relevante Bilder werden lokal gespeichert | `body` als letzte Rückfallstufe | +| **Allgemeine HTML-Seite** | Sichtbares DOM, bevorzugt `article`, `main` oder `[role="main"]` | Überschriften, Absätze, Links, Listen, Zitate, Codeblöcke und Tabellen | Inhaltlich relevante Bilder werden lokal gespeichert | `body` als letzte Rückfallstufe | ### Reihenfolge der Erkennung -SourceBraid verwendet immer die inhaltlich hochwertigste verfügbare Quelle. Bei HTML-Seiten werden die Adapter in dieser Reihenfolge geprüft: +SourceBraid verwendet immer die inhaltlich hochwertigste verfügbare Quelle. Bei +HTML-Seiten werden die Adapter in dieser Reihenfolge geprüft: 1. arXiv-HTML 2. Azure DevOps Wiki @@ -80,25 +121,28 @@ SourceBraid verwendet immer die inhaltlich hochwertigste verfügbare Quelle. Bei 8. Blogger API 9. Google-DeepMind-Blog-DOM 10. JSON Feed, RSS oder Atom -11. sichtbarer DOM +11. sichtbares DOM -Die erste passende und validierte Quelle gewinnt. Anschließend normalisiert SourceBraid das Markdown, lädt Bilder herunter, schreibt das YAML-Frontmatter und aktualisiert den Index. +Die erste passende und validierte Quelle gewinnt. Anschließend normalisiert +SourceBraid das Markdown, lädt Bilder herunter, schreibt das YAML-Frontmatter +und aktualisiert den Index. ## Ablagestruktur Markdown-Dateien werden über die GitHub Contents API gespeichert: ```text -web-clips/YYYY/MM/YYYY-MM-DD-domain-titel-urlhash.md +web-clips/YYYY/MM/YYYY-MM-DD-domain-title-urlhash.md ``` Die zugehörigen Assets liegen unter: ```text -web-clips/YYYY/MM/assets/YYYY-MM-DD-domain-titel-urlhash/ +web-clips/YYYY/MM/assets/YYYY-MM-DD-domain-title-urlhash/ ``` -Links auf gespeicherte Bilder werden im Markdown relativ zu diesem Asset-Ordner geschrieben. Für PDFs liegt dort zusätzlich das Original als `source.pdf`. +Links auf gespeicherte Bilder werden im Markdown relativ zu diesem Asset-Ordner +geschrieben. Für PDFs liegt dort zusätzlich das Original als `source.pdf`. SourceBraid pflegt außerdem einen nach URL-Hash geshardeten Metadatenindex: @@ -108,82 +152,137 @@ web-clips/index/00.jsonl web-clips/index/ff.jsonl ``` -Dieselbe URL landet immer im selben Shard. Dadurch muss beim Speichern nicht der Metadatenbestand aller Clips neu geschrieben werden. Bestehende Archive mit `web-clips/index.jsonl` bleiben kompatibel und können über das Codex-Plugin atomar migriert werden. Jede Indexzeile enthält unter anderem Titel, Quell-URL, Repository-Pfad, Ablagedatum, optionale Veröffentlichungs- und Änderungsdaten, Tags, Quellentyp, Extraktionsmethode, Erfassungszeitpunkt und gespeicherte Bildpfade. `date` und der Pfad `YYYY/MM` verwenden das lokale Ablagedatum; das Veröffentlichungsdatum der Quelle bleibt separat als `published` erhalten. +Dieselbe URL landet immer im selben Shard. Dadurch muss beim Speichern nicht der +gesamte Metadatenbestand neu geschrieben werden. Bestehende Archive mit +`web-clips/index.jsonl` bleiben kompatibel und können über das Plugin atomar +migriert werden. Jeder Eintrag enthält Titel, kanonische URL, Repository-Pfad, +Erfassungsdatum, optionale Veröffentlichungs- und Änderungsdaten, Tags, +Quellentyp, +Extraktionsmethode, Erfassungszeitpunkt und gespeicherte Bildpfade. `date` und +der Pfad `YYYY/MM` verwenden das lokale Erfassungsdatum; das +Veröffentlichungsdatum der Quelle bleibt separat als `published` erhalten. -## Wissenschaftliche Quellen +## Wissenschaftliche Veröffentlichungen und PDFs ### arXiv direkt als Markdown -Eine arXiv-Abstract-Seite wie `https://arxiv.org/abs/2311.02462` kann direkt gespeichert werden. SourceBraid lädt bevorzugt die experimentelle HTML-Ausgabe des vollständigen Papers, konvertiert sie in Markdown und übernimmt wissenschaftliche Metadaten. Das PDF muss dafür weder manuell heruntergeladen noch in Chrome geöffnet werden. +Eine arXiv-Abstract-Seite wie `https://arxiv.org/abs/2311.02462` kann direkt +gespeichert werden. SourceBraid lädt bevorzugt die experimentelle HTML-Ausgabe +des vollständigen Papers, konvertiert sie in Markdown und übernimmt +wissenschaftliche Metadaten. Das PDF muss dafür weder manuell heruntergeladen +noch geöffnet werden. -Existiert keine HTML-Ausgabe, lädt die Erweiterung das PDF im Hintergrund in das Repository. Der Docling-Workflow übernimmt danach automatisch die Konvertierung. +Existiert keine HTML-Ausgabe, lädt die Erweiterung das PDF im Hintergrund in +das Repository hoch. Der Docling-Workflow übernimmt danach automatisch die +Konvertierung. ### Allgemeine PDFs -SourceBraid unterstützt sowohl PDF-URLs über HTTP(S) als auch lokale, in Chrome geöffnete `.pdf`-Dateien. Für lokale Dateien muss unter `chrome://extensions` in den Details von SourceBraid einmalig **Zugriff auf Datei-URLs zulassen** aktiviert sein. Ist die Berechtigung nicht gesetzt, zeigt die Erweiterung eine konkrete Anleitung an und legt keinen leeren HTML-Clip an. +SourceBraid unterstützt sowohl PDF-URLs über HTTP(S) als auch lokale, in Chrome +geöffnete `.pdf`-Dateien. Für lokale Dateien muss unter `chrome://extensions` in +den Details von SourceBraid einmalig **Zugriff auf Datei-URLs zulassen** +aktiviert sein. Ist die Berechtigung nicht gesetzt, zeigt die Erweiterung eine +konkrete Anleitung an und legt keinen leeren HTML-Clip an. -Ein PDF-Tab wird zunächst so abgelegt: +Bei der Erfassung eines PDFs wird zunächst Folgendes gespeichert: ```text web-clips/YYYY/MM/assets/CLIP-SLUG/source.pdf ``` -Die Erweiterung erstellt vorab einen ausstehenden Markdown-Eintrag und einen Indexdatensatz. Der abschließende PDF-Commit startet `.github/workflows/convert-pdfs.yml`. Der Workflow: +Die Erweiterung erstellt vorab einen Markdown-Eintrag mit Status `pending` und +einen Metadateneintrag. Der abschließende PDF-Commit startet +`.github/workflows/convert-pdfs.yml`. Der Workflow: 1. installiert Docling auf einem GitHub-Runner, 2. extrahiert Lesereihenfolge, Tabellen, OCR-Text und Abbildungen, -3. ersetzt das ausstehende Markdown unter Beibehaltung von Notizen und Frontmatter, -4. markiert den passenden Indexeintrag als abgeschlossen und +3. ersetzt den ausstehenden Markdown-Eintrag unter Beibehaltung von Notizen und + Frontmatter, +4. markiert den passenden Metadateneintrag als abgeschlossen und 5. behält das Original-PDF neben den extrahierten Assets. -GitHub Actions benötigt Schreibzugriff auf Repository-Inhalte. Der Workflow hat ein Zeitlimit von 45 Minuten; einzelne PDFs sind wegen der Browser- und GitHub-API-Speichergrenzen auf 25 MB begrenzt. Eine erneute Konvertierung ist unter **Actions → Convert PDFs to Markdown → Run workflow** möglich. +GitHub Actions benötigt Schreibzugriff auf Repository-Inhalte. Der Workflow hat +ein Zeitlimit von 45 Minuten; einzelne PDFs sind wegen der Größenbeschränkungen +von Browser und GitHub API auf 25 MB begrenzt. Eine erneute Konvertierung ist +unter **Actions → Convert PDFs to Markdown → Run workflow** möglich. -Wenn während einer laufenden Konvertierung weitere Clips auf demselben Branch gespeichert werden, aktualisiert der Workflow seinen Branch vor dem Push erneut und wiederholt einen abgelehnten Push bis zu fünfmal. Dadurch gehen parallele SourceBraid-Uploads nicht durch einen kurzzeitigen Git-Ref-Konflikt verloren. +Wenn während einer laufenden Konvertierung weitere Clips auf demselben Branch +gespeichert werden, aktualisiert der Workflow seinen Branch vor dem Push erneut +und wiederholt einen abgelehnten Push bis zu fünfmal. Dadurch gehen parallele +SourceBraid-Uploads nicht durch einen kurzzeitigen Git-Ref-Konflikt verloren. ## Wikis und Gists mit Bildern ### Azure DevOps Wiki -SourceBraid ruft das Quell-Markdown über die authentifizierte Azure-DevOps-Wiki-API ab. Falls dies nicht möglich ist, wird ausschließlich der gerenderte Bereich `.markdown-content` konvertiert – nicht Navigation, Kopfzeile oder sonstige Azure-DevOps-Oberfläche. +SourceBraid ruft das Quell-Markdown über die authentifizierte +Azure-DevOps-Wiki-API ab. Falls dies nicht möglich ist, wird ausschließlich der +gerenderte Bereich `.markdown-content` konvertiert – nicht Navigation, Kopfzeile +oder sonstige Azure-DevOps-Oberfläche. -Da Attachment-URLs die angemeldete Browser-Sitzung benötigen können, lädt SourceBraid die Bilder nacheinander über den geöffneten Quell-Tab, speichert sie im Asset-Ordner und ersetzt die URLs durch relative Repository-Pfade. Der Quell-Tab muss deshalb bis zum Abschluss des Speicherns geöffnet bleiben. Im Frontmatter werden Organisation, Projekt, Wiki-ID, Seiten-ID, Seitenpfad und – soweit verfügbar – Revision festgehalten. +Da geschützte Anhang-URLs die bestehende authentifizierte Browser-Sitzung +benötigen können, lädt SourceBraid die Bilder nacheinander über den geöffneten +Quell-Tab, speichert sie im Asset-Ordner und ersetzt die URLs durch relative +Repository-Pfade. Der Quell-Tab muss deshalb bis zum Abschluss des Speicherns +geöffnet bleiben. Im Frontmatter werden Organisation, Projekt, Wiki-ID, +Seiten-ID, Seitenpfad und – soweit verfügbar – Revision festgehalten. ### GitHub Gists -Bei einem Gist wird eine einzelne Markdown-Datei direkt als Dokumentinhalt gespeichert. Mehrdatei-Gists werden zu einem Dokument mit einem Abschnitt je Dateiname zusammengeführt; Nicht-Markdown-Dateien bleiben als sprachlich markierte Codeblöcke erhalten. +Bei einem Gist mit nur einer Markdown-Datei wird diese direkt als +Dokumentinhalt übernommen. Gists mit mehreren Dateien werden zu einem Dokument +mit einem Abschnitt je Dateiname zusammengeführt; Nicht-Markdown-Dateien bleiben +als Codeblöcke mit Sprachkennung erhalten. -Öffentliche Gists funktionieren anonym. Für private Gists verwendet SourceBraid zusätzlich den konfigurierten GitHub-Token, sofern dieser Leserechte für Gists besitzt. GitHub-gehostete Benutzerbilder können über den weiterhin geöffneten, angemeldeten Gist-Tab geladen werden. +Öffentliche Gists funktionieren anonym. Für private Gists verwendet SourceBraid +zusätzlich den konfigurierten GitHub-Token, sofern dieser Leserechte für Gists +besitzt. Zugriffsgeschützte GitHub-Bilder können über den weiterhin geöffneten +Gist-Tab mit aktiver GitHub-Sitzung geladen werden. -## Installation und Verwendung +## Chrome-Installation 1. `chrome://extensions` öffnen. 2. **Entwicklermodus** aktivieren. 3. **Entpackte Erweiterung laden** auswählen. 4. [`chrome-extension/sourcebraid`](chrome-extension/sourcebraid) auswählen. 5. Eine unterstützte Quelle öffnen und auf das **SourceBraid**-Symbol klicken. -6. GitHub-Repository konfigurieren, optional Tags oder Notizen ergänzen und **Save to GitHub** wählen. +6. Das private GitHub-Repository konfigurieren, optional Tags oder Notizen + ergänzen und **Save to GitHub** wählen. -Nach der ersten Einrichtung bleiben die GitHub-Einstellungen hinter dem Einstellungssymbol im Popup verborgen. Scheitert nur der GitHub-Upload nach einer erfolgreichen Extraktion, steht im Popup **Download Fallback** zur Verfügung. Vor dem Upload prüft SourceBraid, ob das konfigurierte Repository existiert und für den Token erreichbar ist; bei `404 Not Found` zeigt das Popup einen eindeutigen Fehler an. +Nach der ersten Einrichtung bleiben die GitHub-Einstellungen hinter dem +Einstellungssymbol im Popup eingeklappt. Scheitert nur der GitHub-Upload nach +einer erfolgreichen Extraktion, steht im Popup **Download Fallback** zur +Verfügung. Vor dem Upload prüft SourceBraid, ob das konfigurierte Repository +existiert und mit dem Token zugänglich ist; bei `404 Not Found` zeigt das Popup +einen eindeutigen Fehler an. ## GitHub-Token -Empfohlen wird ein Fine-grained Personal Access Token, der auf genau ein privates Repository beschränkt ist: +Verwende ein Fine-grained Personal Access Token, das auf genau ein privates +Repository beschränkt ist: ```text Contents: Read and write Workflows: Read and write ``` -`Workflows` ist nur für die PDF-Unterstützung erforderlich. Beim ersten PDF-Upload installiert SourceBraid den mitgelieferten Docling-Workflow, das Konvertierungsskript und die Requirements-Datei, sofern diese Pfade noch nicht existieren. Bestehende Dateien werden nicht überschrieben. Der Token wird lokal im Chrome-Erweiterungsspeicher abgelegt. +`Workflows` ist nur für die PDF-Unterstützung erforderlich. Beim ersten +PDF-Upload installiert SourceBraid den mitgelieferten Docling-Workflow, das +Konvertierungsskript und die Requirements-Datei, sofern diese Pfade noch nicht +existieren. Bestehende Dateien werden nicht überschrieben. Der Token wird lokal +im Chrome-Erweiterungsspeicher abgelegt. Optionale API-Einstellungen: -- Ghost Content API: Basis-URL, zum Beispiel `https://example.com/ghost/api/content`, plus browsergeeigneter Content-API-Key -- Blogger: optionaler Google API Key; öffentliche Posts benötigen kein OAuth, anonyme API-Aufrufe normalerweise aber einen Key für das Kontingent +- Ghost Content API: Basis-URL, zum Beispiel + `https://example.com/ghost/api/content`, plus browsergeeigneter Content-API-Key +- Blogger: optionaler Google API Key; öffentliche Posts benötigen kein OAuth, + anonyme API-Aufrufe normalerweise aber einen Key für das Kontingent ## SourceBraid in ChatGPT und Codex -Über **Export Plugin Config** kann die Datei `sourcebraid-config.json` heruntergeladen werden. Für das SourceBraid-Codex-Plugin wird sie hier abgelegt: +**Export Plugin Config** lädt `sourcebraid-config.json` herunter. Speichere die +Datei unter: ```text ~/.config/sourcebraid/config.json @@ -192,10 +291,14 @@ Optionale API-Einstellungen: Alternativ lässt sich das Plugin im Terminal konfigurieren: ```bash -python3 codex-plugin/sourcebraid/scripts/sourcebraid.py config --repo-slug OWNER/REPO --branch main --root-folder web-clips +python3 codex-plugin/sourcebraid/scripts/sourcebraid.py config \ + --repo-slug OWNER/REPO --branch main --root-folder web-clips ``` -Das versionierte Plugin liegt unter `codex-plugin/sourcebraid`. Es verwendet einen lokalen SQLite-FTS5-Index, lädt bei Aktualisierungen nur anhand der Git-Blob-SHAs geänderte Dateien und unterstützt Suche, Abruf sowie eine abgesicherte Löschvorschau: +Das versionierte Plugin liegt unter `codex-plugin/sourcebraid`. Es verwendet +einen lokalen SQLite-FTS5-Index, lädt nur Dateien herunter, deren Git-Blob-SHAs +sich geändert haben, und unterstützt Suche, Abruf, Auflistung sowie abgesicherte +Löschvorschauen: ```bash python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index build @@ -203,36 +306,57 @@ python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index update --max-age 9 python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index verify python3 codex-plugin/sourcebraid/scripts/sourcebraid.py search "dynamic agents" --tag ai python3 codex-plugin/sourcebraid/scripts/sourcebraid.py list "dynamic agents" --refresh -python3 codex-plugin/sourcebraid/scripts/sourcebraid.py plan-delete --path "web-clips/2026/07/example.md" --json +python3 codex-plugin/sourcebraid/scripts/sourcebraid.py plan-delete \ + --path "web-clips/2026/07/example.md" --json ``` -Der Index liegt pro Repository und Branch unter `~/.cache/sourcebraid/.../search.sqlite3` und wird nicht in Git gespeichert. Eine Suche prüft höchstens alle 15 Minuten, ob sich der Remote-Head geändert hat; bei einem Netzfehler bleibt der lokale Index nutzbar. `search --scan` steht als ausdrücklicher `rg`-Fallback zur Verfügung. +Der Index liegt pro Repository und Branch unter +`~/.cache/sourcebraid/.../search.sqlite3` und wird nicht in Git gespeichert. +Eine Suche prüft höchstens alle 15 Minuten, ob sich der Remote-Head geändert +hat; wenn GitHub nicht erreichbar ist, bleibt der lokale Index nutzbar. +`search --scan` ist ein expliziter Diagnose-Fallback auf Basis von `rg`. -Neue Captures schreiben Metadaten in stabile URL-Hash-Shards wie `web-clips/index/47.jsonl`, damit nicht mehr bei jedem Speichern eine globale `index.jsonl` umgeschrieben wird. Bestehende Archive bleiben lesbar. Die einmalige Migration wird zuerst angezeigt und anschließend mit dem unveränderten Head bestätigt: +Neue Captures schreiben stabile URL-Hash-Shards wie +`web-clips/index/47.jsonl`. Bestehende Archive bleiben lesbar. Vor der +einmaligen Migration wird eine Vorschau erstellt; anschließend wird die +Migration anhand des unveränderten Branch-Heads bestätigt: ```bash python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index plan-shards --json -python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index migrate-shards --expected-head HEAD_SHA --confirm-head HEAD_SHA --json +python3 codex-plugin/sourcebraid/scripts/sourcebraid.py index migrate-shards \ + --expected-head HEAD_SHA --confirm-head HEAD_SHA --json ``` -Vor einer Löschung zeigt das Plugin exakt das betroffene Markdown, die Indexänderung und zugehörige Assets und verlangt eine erneute ausdrückliche Bestätigung. Die Änderung wird als normaler, nicht erzwungener Git-Commit gespeichert und bleibt damit über die Git-Historie wiederherstellbar. +Vor einer Löschung zeigt das Plugin genau die betroffene Markdown-Datei, die +vorgesehene Metadatenänderung und die ausschließlich diesem Clip zugehörigen +Assets an und verlangt anschließend eine ausdrückliche Bestätigung. Es +speichert die Änderung als normalen Git-Commit ohne erzwungenes Überschreiben, +sodass sie über die Git-Historie wiederherstellbar bleibt. -Das Plugin enthält zusätzlich einen lokalen MCP-Server mit den standardisierten -Werkzeugen `search` und `fetch`, damit dieselbe Installation in ChatGPT und -Codex verwendet werden kann. Hinweise zur lokalen Installation und zum späteren -öffentlichen HTTPS-Endpunkt stehen in +Das Plugin umfasst außerdem einen lokalen MCP-Server mit den Standardwerkzeugen +`search` und `fetch` für Codex. Solange der Dienst nicht öffentlich +bereitgestellt ist, benötigt ChatGPT einen privaten Secure MCP Tunnel. Hinweise +zur lokalen Codex-Einrichtung und zum späteren ChatGPT-Endpunkt stehen in [`docs/CHATGPT_PLUGIN.md`](docs/CHATGPT_PLUGIN.md). +## iOS + +Die native iOS-App und Share Extension liegen unter [`ios/`](ios/README.md). +Nach einmaliger Einrichtung von Repository und Token können URLs, ausgewählter +Text, Safari-Artikel, PDFs und andere Dateien über das Teilen-Menü an das +konfigurierte private Archiv gesendet werden. + ## Android-Roadmap -Die Android-Share-App ist bewusst noch nicht Teil der ersten Veröffentlichung. -Nach dem Feedback aus der OpenAI-Community wird anhand der Nachfrage und -möglicher Mitwirkender entschieden, ob sie als nächster nativer Client gebaut -wird. +Android ist bewusst nicht Teil der ersten Veröffentlichung. Das Feedback aus +der OpenAI-Community entscheidet darüber, ob ein Android-Share-Target der +nächste native Client wird und welche Mitwirkenden oder Testpersonen seine +Entwicklung mitgestalten können. ## Mitwirken und Lizenz -SourceBraid wird vollständig unter der [MIT-Lizenz](LICENSE) veröffentlicht. +SourceBraid ist vollständig Open Source und wird unter der +[MIT-Lizenz](LICENSE) veröffentlicht. Hinweise für Beiträge und den DCO-Sign-off stehen in [CONTRIBUTING.md](CONTRIBUTING.md). Der [Verhaltenskodex](CODE_OF_CONDUCT.md) regelt die Zusammenarbeit, die @@ -240,18 +364,16 @@ Hinweise für Beiträge und den DCO-Sign-off stehen in Der [öffentliche Release-Prozess](RELEASING.md) beschreibt Versionierung, Prüfungen und reproduzierbare Release-Artefakte. [Datenschutz](PRIVACY.md), [Nutzungsbedingungen](TERMS.md) und der -[Hinweis](NOTICE) dokumentieren Datenfluss und Lizenzgrenzen. - -## iOS - -Die native iOS-App und Share Extension liegen unter [`ios/`](ios/README.md). Nach einmaliger Einrichtung von Repository und Token können URLs, ausgewählter Text, Safari-Artikel, PDFs und andere Dateien über das Teilen-Menü im konfigurierten privaten Archiv-Repository gespeichert werden. +[Hinweis](NOTICE) dokumentieren den lokalen, vom Benutzer kontrollierten +Datenfluss und die Lizenzgrenzen. ## Technische Hinweise Der Quellcode der Chrome-Erweiterung liegt unter [`chrome-extension/sourcebraid`](chrome-extension/sourcebraid). Die Erweiterung -benötigt keinen Build-Schritt und bündelt keine Drittanbieter-Runtime. Docling -läuft ausschließlich in der GitHub Action des Ziel-Repositorys. Die +benötigt keinen Build-Schritt und bindet keine Laufzeitkomponenten von +Drittanbietern ein. Docling läuft ausschließlich in der GitHub Action des +Ziel-Repositorys. Die HTML-Konvertierung erfolgt lokal in der Erweiterung; API- und Bildzugriffe -nutzen je nach Quelle entweder normale HTTP-Anfragen oder die vorhandene -angemeldete Browser-Sitzung. +nutzen je nach Quelle entweder normale HTTP-Anfragen oder die bestehende +authentifizierte Browser-Sitzung. diff --git a/README.md b/README.md index 4dd52c2..5518ba7 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ index repair. | **Remote or local PDF** | Original PDF plus asynchronous Docling workflow in GitHub Actions | Reading order, tables, OCR text, and referenced figures; starts as `pending`, then becomes finished Markdown | The original remains as `source.pdf`; extracted figures sit beside it | Local PDFs require Chrome's **Allow access to file URLs** setting; encrypted or session-only PDFs are unsupported | | **Azure DevOps Wiki** | Authenticated Wiki REST API returns source Markdown | Azure macros are normalized, Mermaid remains a `mermaid` code block, internal wiki links become absolute | Protected attachments are loaded through the still-authenticated source tab | Rendered `.markdown-content` area | | **GitHub Gist** | GitHub Gist API, with the configured token for private Gists | A single Markdown file directly; multiple files as sections; source code in language-tagged fences | Public images directly, protected GitHub images through the signed-in Gist tab | Revision-specific URLs keep their revision | -| **Native Markdown** | HTTP response to `Accept: text/markdown` | Source frontmatter and duplicate H1 removed; relative links made absolute | Relevant images are stored locally and linked relatively | Continue through dedicated APIs, then DOM extraction | +| **Native Markdown** | HTTP response to `Accept: text/markdown`, for example from Hashnode or appropriately configured Cloudflare sites | Source frontmatter and duplicate H1 removed; relative links made absolute | Relevant images are stored locally and linked relatively | Continue through dedicated APIs, then DOM extraction | | **WordPress** | WordPress REST endpoint discovered from page metadata | Article content converted from structured API data | Relevant article images stored locally | Visible page content | | **Forem / DEV** | Forem API with source Markdown | Normalized Markdown without site chrome | Relevant images stored locally | Visible page content | | **Ghost** | Configured Ghost Content API | Structured post content with canonical URL validation | Relevant images stored locally | Visible page content | @@ -148,6 +148,8 @@ metadata collection on each capture. Existing archives with the plugin. Each entry includes title, canonical URL, repository path, capture date, optional publication and modification dates, tags, source type, extraction method, capture timestamp, and saved image paths. +`date` and the `YYYY/MM` path use the local capture date; a source's publication +date remains separate in `published`. ## Research papers and PDFs @@ -203,7 +205,8 @@ not navigation, headers, or unrelated Azure DevOps UI. Protected attachment URLs may need the browser's signed-in session, so SourceBraid loads images sequentially through the open source tab, stores them in the asset folder, and rewrites links to relative repository paths. Keep the -source tab open until capture completes. +source tab open until capture completes. The frontmatter records the +organization, project, wiki ID, page ID, page path, and revision when available. ### GitHub Gists @@ -248,8 +251,10 @@ The token is stored locally in Chrome extension storage. Optional API configuration: -- Ghost Content API: base URL plus a browser-safe Content API key -- Blogger: optional Google API key for anonymous public API quota +- Ghost Content API: base URL, such as `https://example.com/ghost/api/content`, + plus a browser-safe Content API key +- Blogger: optional Google API key; public posts do not require OAuth, but + anonymous API calls normally need a key for quota ## SourceBraid in ChatGPT and Codex @@ -301,9 +306,9 @@ owned assets, then requires explicit confirmation. It writes a normal, non-forced Git commit, so repository history remains recoverable. The plugin also includes a local MCP server with standard `search` and `fetch` -tools, enabling the same installation in ChatGPT and Codex. See -[`docs/CHATGPT_PLUGIN.md`](docs/CHATGPT_PLUGIN.md) for local setup and the future -public HTTPS endpoint. +tools for Codex. ChatGPT requires a private Secure MCP Tunnel while the service +is not publicly deployed. See [`docs/CHATGPT_PLUGIN.md`](docs/CHATGPT_PLUGIN.md) +for the local Codex setup and the later ChatGPT endpoint. ## iOS