chore: updated readme

2026-02-27 13:51:01 +01:00
parent ecafdcf606
commit 69b3f61073
1 changed files with 57 additions and 24 deletions
--- a/README.md
+++ b/README.md
@@ -6,17 +6,31 @@ Desktop-first blogging workspace built with Electron + TypeScript + React + SQLi

 Implemented and actively used:

- **Offline-first by default** with full local editing, preview, and git-based workflows; all online features are optional
+- **Offline-first by default** — full local editing, preview, generation, and git-based workflows; all online features are optional
 - **Multi-project workflow** with active project switching and optional custom data paths
- **Post management** (draft/published/archived), pagination, filtering, full-text search, canonical URL handling
- **Media pipeline** with import, metadata sidecars, thumbnails, linked-media references, and cleanup tooling
- **Tag management** including merge/rename/sync from content
- **WordPress WXR import pipeline** (analysis, import definitions, execution/progress)
- **Preview server** with local assets only, Liquid templates, macro processing, archive routes, sitemap generation
- **Git integration** (status, diff, history, fetch/pull/push, init, .gitignore ensure, LFS prune)
- **Metadata diff tooling** for comparing filesystem metadata vs database metadata
- **AI chat persistence layer** (conversations/messages/model metadata) with OpenCode integration support
- **Task system** for progress reporting across long-running operations
+- **Post & page management** (draft/published/archived), pagination, filtering, multi-language full-text search (Snowball stemming), canonical URL handling, inter-post link graph with backlinks/outlinks
+- **Media pipeline** with import, metadata sidecars, three thumbnail sizes (Sharp), linked-media references, and cleanup tooling
+- **Tag management** including merge/rename/sync from content, color support
+- **Menu editor** for hierarchical site navigation (OPML-based), with page picker and submenu nesting
+- **WordPress WXR import pipeline** (analysis, import definitions, 4-phase execution with progress tracking, HTML-to-Markdown conversion)
+- **Blogmark deep links** — `bds://new-post` custom protocol for one-click bookmark saving from any browser, with bookmarklet generation and transform script pipeline
+- **Static site generation** — full blog output with single-post pages, paginated category/tag/date archive routes, standalone page routes, plus `sitemap.xml`, `rss.xml`, `atom.xml`, and `calendar.json`; content-hash-based incremental writes
+- **Site validation** — compares sitemap against generated HTML, detects missing/extra/stale pages, and auto-repairs with targeted re-rendering
+- **SSH publishing** via `scp` or `rsync` with parallel upload of HTML, thumbnails, and media
+- **Preview server** with local assets only, Liquid templates, macro processing, archive routes, draft preview support, and style preview
+- **Style & theming** — 19 Pico CSS color themes with live preview (auto/light/dark modes), all assets served locally
+- **Python scripting** (Pyodide WebAssembly runtime) — three script kinds:
+    - *Transform scripts* — modify incoming blogmark posts before creation
+    - *Macro scripts* — custom `[[macro_name ...]]` blocks that expand during preview/generation, with full access to the bDS Python API (~65+ methods)
+    - *Utility scripts* — general-purpose Python automation
+- **Built-in macros** — `youtube`, `vimeo`, `gallery` (lightbox), `photo_archive`, `tag_cloud` (D3 word cloud)
+- **Liquid template system** for all generated pages with i18n support (English, German, French, Italian, Spanish) and custom Markdown filter with internal link rewriting
+- **AI assistant** (OpenCode Zen API, supporting Claude, GPT-5, Gemini 3, and more) with streaming responses, tool use (search/read/update posts, media analysis including image vision, blog stats), and rich interactive responses via the A2UI protocol (charts, tables, forms, cards, metrics, lists, tabs)
+- **Git integration** (status, diff, commit history with sync status, fetch/pull/push, init, .gitignore management, LFS configure/prune, branch operations)
+- **Metadata diff tooling** for comparing filesystem metadata vs database metadata with sync in either direction
+- **Rich editing** — Milkdown WYSIWYG Markdown editor for posts, Monaco code editor for Python scripts
+- **Task system** for background progress reporting across long-running operations with grouping, cancellation, and status bar integration
+- **i18n** — UI language follows OS locale; render/preview language from project preferences; 5 supported languages

 ## Architecture

@@ -25,25 +39,36 @@ src/
 ├── main/
 │   ├── database/        # Drizzle schema, migrations, connection
 │   ├── engine/          # Core business logic (no UI)
-│   │   ├── PostEngine
-│   │   ├── MediaEngine
-│   │   ├── PostMediaEngine
-│   │   ├── ProjectEngine
-│   │   ├── MetaEngine
-│   │   ├── TagEngine
-│   │   ├── PreviewServer
-│   │   ├── Import* engines
-│   │   ├── GitEngine
-│   │   ├── MetadataDiffEngine
-│   │   ├── ChatEngine / OpenCodeManager
-│   │   └── TaskManager
+│   │   ├── PostEngine             # Post CRUD, FTS indexing, link graph
+│   │   ├── MediaEngine            # Media files, Sharp thumbnails
+│   │   ├── PostMediaEngine        # Post ↔ media linking
+│   │   ├── ProjectEngine          # Multi-project management
+│   │   ├── MetaEngine             # Project metadata, categories
+│   │   ├── TagEngine              # Tag CRUD, merge, rename, colors
+│   │   ├── ScriptEngine           # Python script management & Git sync
+│   │   ├── MenuEngine             # OPML-based navigation menus
+│   │   ├── PreviewServer          # Local HTTP preview with Liquid
+│   │   ├── BlogGenerationEngine   # Static site generation
+│   │   ├── PublishEngine          # SSH upload (scp / rsync)
+│   │   ├── SiteValidationDiffService  # Sitemap ↔ HTML validation
+│   │   ├── Import* engines        # WXR parsing, analysis, execution
+│   │   ├── Blogmark* services     # Deep link handling, transforms
+│   │   ├── PythonMacroWorkerRuntime   # Pyodide macro execution
+│   │   ├── GitEngine              # Git operations (simple-git)
+│   │   ├── MetadataDiffEngine     # DB ↔ file metadata comparison
+│   │   ├── ChatEngine / OpenCodeManager  # AI chat & model integration
+│   │   └── TaskManager            # Background task queue
+│   ├── a2ui/            # A2UI protocol: types, catalog, generator
 │   ├── ipc/             # IPC handlers; bridges renderer to engines
 │   ├── shared/          # Shared contracts/types (Electron API)
 │   └── main.ts          # Electron app + menu + window lifecycle
 └── renderer/
        ├── components/      # UI (editor, sidebars, panels, modals, views)
+        ├── a2ui/            # A2UI surface rendering (17 component types)
        ├── store/           # Zustand app state
        ├── macros/          # Macro authoring/runtime support
+        ├── python/          # Python scripting UI integration
+        ├── navigation/      # Activity routing, tab policy, sidebar views
        └── App.tsx          # App composition + event wiring
 ```

@@ -62,8 +87,9 @@ Typical per-project folders:
 {projectDataDir}/
 ├── posts/
 ├── media/
-├── meta/
-└── thumbnails/
+├── meta/          # tags, categories, menu.opml
+├── scripts/       # Python scripts (.py with YAML frontmatter)
+└── thumbnails/    # small / medium / large
 ```

 ## Menu / Shortcuts (Cross-Platform)
@@ -135,6 +161,7 @@ npm run dist:linux
 ### Distribution Notes

 - Custom protocol `bds://` is declared in electron-builder metadata for packaged apps.
+- Build targets: macOS (DMG+ZIP, arm64, notarized), Windows (NSIS, x64+arm64), Linux (AppImage/deb/rpm).
 - macOS signing/notarization is scaffolded via `scripts/notarize.mjs` and runs when these env vars are set:
    - `APPLE_ID`
    - `APPLE_APP_SPECIFIC_PASSWORD`
@@ -148,6 +175,12 @@ npm run db:migrate
 npm run db:studio
 ```

+## Further Documentation
+
+- [DOCUMENTATION.md](DOCUMENTATION.md) — end-user guide covering workflows, macros, scripting, AI assistant, and editorial best practices
+- [API.md](API.md) — full Python runtime API reference for macro and utility scripts (`bds_api` module)
+- [VISION.md](VISION.md) — long-term product vision and design notes
+
 ## License

 MIT