A deployable markdown editor that connects with your self hosted files and lets you edit in a beautiful interface
markedit PLAN.md
10 kB · 212 lines
Markdown
at main

MarkEdit → General Markdown Editor: Master Plan #

Transform MarkEdit from a GitHub-only blog-post editor into a general-purpose markdown editor with pluggable storage connectors, a public (unauthenticated) editing experience, and a Linear-quality UI.

Core Decisions (locked) #

  1. Public editor first — no landing page. The app opens directly into an editor. Logged-out users get multiple local documents (browser storage). To persist documents beyond the browser, users log in with ATProto.
  2. Document model — public documents are published onto the AT Protocol; private documents stay in MarkEdit's DB and will be shareable peer-to-peer via iroh (planned, not built in this phase).
  3. Connectors = ports & adapters (onion architecture) — ATProto is just a connector, exactly like GitHub. Nothing protocol-specific lives in the core. First ATProto adapter: PDS lexicon records only. Tangled (git) comes later.
  4. Theme — system-following, with both light and dark themes.
  5. Publish semantics — all documents are saved to MarkEdit's DB first (staging). "Publish" adapts per connector rules:
    • ATProto (PDS records) → direct write (putRecord / deleteRecord)
    • GitHub → branch + commit + pull request (current behavior)
    • Tangled (future) → commit + push to knot
  6. Editor as a package — the frontend editor is isolated in a package-like structure (@markedit/editor) from day one, so it can be published and reused in other apps later. Not feature-complete as a package yet — just structured correctly.

Architecture #

Onion / ports & adapters #

┌────────────────────────────────────────────────────┐
│  Adapters (outer)                                  │
│  connectors/github   connectors/atproto (pds)      │
│  auth/github-oauth   auth/atproto-oauth            │
│  share/iroh (future)                               │
├────────────────────────────────────────────────────┤
│  Ports (interfaces)                                │
│  Connector · AuthProvider · ShareTransport         │
├────────────────────────────────────────────────────┤
│  Core (inner, dependency-free)                     │
│  domain: Document, Connection, Identity            │
│  services: DocumentService, PublishService         │
└────────────────────────────────────────────────────┘
  • Core knows about documents, drafts, connections, publish intents. It never imports a protocol SDK.
  • Ports are Go interfaces. Connector already exists (internal/connectors/connector.go) and will be extended.
  • Adapters implement ports. Each connector declares capabilities (Capabilities() → canPullRequest, canDirectWrite, supportsFolders, isPublicByDefault, ...) so the UI and publish pipeline adapt per source.

Document-centric data model #

Today the app is repo/file-centric. The new core entity is the Document:

Document {
  id, owner_id (nullable → local/anonymous),
  title, content, frontmatter,
  visibility: public | private,
  binding: null | { connection_id, remote_ref, remote_sha, sync_state },
  created_at, updated_at
}
  • A document may be unbound (scratch/local) or bound to a connection
    • remote ref (GitHub owner/repo/path, ATProto at://did/collection/rkey).
  • Saving always writes to MarkEdit's DB. Publishing syncs DB → remote per connector rules and records the result.

New/changed tables (SQLite migrations) #

  • documents — as above (absorbs the current drafts/pending-changes role)
  • identities — (user_id, provider, provider_user_id, ...) decouples users from GitHub (today users.github_id is the identity)
  • connections — (user_id, connector_type, resource_ref, label, ...) absorbs user_repos; one user → many connections of mixed types
  • publish_log — audit of publish events per document/connection

Editor package layout (@markedit/editor) #

frontend/packages/editor/
  package.json          # @markedit/editor, peerDeps: react, tiptap
  src/
    index.ts            # public API: <MarkdownEditor/>, primitives, types
    components/         # SmartEditor, ClassicEditor, EditorShell,
                        # Toolbar, FrontmatterPanel
    extensions/         # custom tiptap extensions built on top of starter-kit
    lib/                # markdown <-> doc transforms, scroll sync, etc.
    styles/             # editor-scoped CSS (themeable via CSS vars)
    types.ts

Contract: no network, no app state inside the package. Content flows in and out via props (value, onChange, mode, frontmatter, callbacks). The app (frontend/src/) wires it to connectors, drafts, and routing. Consumed via a local workspace dependency; publishable to npm later with no restructuring.

Frontend app shell #

┌──────────────┬─────────────────────────────────────┐
│ Sidebar      │ Top bar: breadcrumb · Smart|Classic │
│ (collapsible)│ toggle · save status · Publish      │
│              ├─────────────────────────────────────┤
│ - connection │                                     │
│   switcher   │   Editor (smart or classic view)    │
│ - doc/file   │                                     │
│   list       │                                     │
└──────────────┴─────────────────────────────────────┘
  • Logged out: sidebar hidden; editor + local document switcher only; subtle "Sign in to save" affordance.
  • Logged in: sidebar appears, collapsible to a slim rail (keyboard toggle).

Milestones #

M0 — Foundations: editor package + design system + app shell #

M1 — Local documents (logged-out experience) #

M2 — Classic view #

M3 — Backend onion refactor #

M4 — ATProto auth #

M5 — ATProto PDS connector (records) #

Future (planned, not scheduled) #


Open questions (resolve when the relevant milestone starts) #

  • Exact lexicon for public markdown documents (own vs community standard)
  • ATProto OAuth: scopes needed (repo:app.markedit.document etc.)
  • Anonymous → authenticated document migration UX (auto-claim vs picker)
  • Whether logged-out classic preview rendering happens fully client-side (yes, presumably — confirm no server render endpoint is wanted)