Something went wrong. Try again.
A deployable markdown editor that connects with your self hosted files and lets you edit in a beautiful interface
Something went wrong. Try again.
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) #
- 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.
- 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).
- 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.
- Theme — system-following, with both light and dark themes.
- 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
- ATProto (PDS records) → direct write (
- 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.
Connectoralready 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, ATProtoat://did/collection/rkey).
- remote ref (GitHub
- 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 (todayusers.github_idis the identity)connections—(user_id, connector_type, resource_ref, label, ...)absorbsuser_repos; one user → many connections of mixed typespublish_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.documentetc.) - 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)