Skip to content

Explain Connect as the way apps use your collections #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
callumalpass merged 1 commit into from
Oct 29, 2026
Merged

Explain Connect as the way apps use your collections #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/pages/beta/index.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
<header class="page-intro">
<h1>Create a Connect account</h1>
<p class="page-intro__lede">
A Connect account syncs and shares your collections.
A Connect account lets apps use your collections, and syncs and shares
them across your devices and with other people.
</p>
<div class="button-row">
<a class="button button--primary" href="https://connect.mdbase.dev/signup">Sign up</a>
Expand Down
157 changes: 69 additions & 88 deletions src/pages/connect/index.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,78 @@ import BaseLayout from "../../layouts/BaseLayout.astro";

<BaseLayout
title="mdbase Connect"
description="mdbase Connect is the account that syncs and shares your Markdown collections. Choose Cloud copy or Private for each collection, approve apps, share with people, and add devices."
description="mdbase Connect lets apps use your Markdown collections as their database. You approve each app, and your records stay as files you own, synced across your devices."
current="connect"
>
<header class="page-intro">
<h1>mdbase Connect</h1>
<p class="page-intro__lede">
Connect is the account that syncs and shares your collections. This page
explains what you choose for each collection, what mdbase can read, and
how apps, people and devices get access.
Connect lets apps use your Markdown collections as their database. An app
doesn’t keep your data in its own storage. It asks for access to one of
your collections, then finds, creates and edits records there, and
every change is saved as a Markdown file you own.
</p>
</header>

<section class="content-section" aria-labelledby="how-it-works">
<h2 id="how-it-works">How it works</h2>
<p>
Say you keep your tasks in a collection. Each task is a Markdown file,
like <code>tasks/renew-passport.md</code>:
</p>
<pre><code>---
type: task
title: Renew passport
status: open
due: 2026-12-01
---

Book a photo appointment first.</code></pre>
<p>
Connect <a href="/apps/">TaskNotes</a> to that collection and it queries
the records of type <code>task</code> to build its lists. Mark this one
done and TaskNotes changes <code>status</code> in the file. Edit the due
date in a text editor and TaskNotes shows the new date. Any other app you
connect to the same collection sees the same records, so nothing has to
be exported from one app to another.
</p>
<p>
Connect is the account that makes this work. It handles sign-in, the
permissions you grant, syncing between your devices, and sharing with
other people.
</p>
</section>

<section class="content-section" aria-labelledby="apps">
<h2 id="apps">Apps ask first</h2>
<p>
When you connect an app, you sign in to Connect, choose one collection,
and see the operations the app asks for before you approve it. You might
let a project planner find, create and edit project records while leaving
deletion blocked.
</p>
<p>
The permission is recorded with the collection, and every copy checks it:
your devices and, for Cloud copy, mdbase’s copy. You can narrow or revoke
a permission at any time. Removing an app never removes the collection,
and your other apps keep using it.
</p>
</section>

<section class="content-section" aria-labelledby="sync-options">
<h2 id="sync-options">Cloud copy or Private</h2>
<p>
When you turn on sync for a collection, every device that syncs it keeps a
complete copy as ordinary files and works offline. Each change is locked
on the device before it leaves. mdbase passes it to your other devices
and can’t read it. You choose one of two options for each collection:
Connect keeps each collection in sync across your devices. Every device
that syncs it keeps a complete copy as ordinary files and keeps working
offline. For each collection, you choose whether mdbase can read it:
</p>
<dl class="glossary-list">
<div>
<dt>Cloud copy</dt>
<dd>
The default for new accounts. mdbase also keeps a readable copy of the
collection and holds its key. Web apps keep working while your devices
are off, and a new device joins when you sign in.
The default. mdbase keeps a readable copy of the collection, so web
apps keep working while your devices are off, and a new device joins
when you sign in.
</dd>
</div>
<div>
Expand All @@ -52,47 +97,16 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
<section class="content-section" aria-labelledby="devices">
<h2 id="devices">Add a device</h2>
<p>
For a Cloud copy collection, sign in on the new device. Once your account
approves it, the device receives the collection key and downloads its
copy. None of your other devices need to be online.
</p>
<p>
Cloud copy needs no encryption password. If you choose Private for a
collection, you set an encryption password when you create your first
Private collection, and mdbase shows you a recovery key once. Keep the
recovery key in a password manager or on paper. To add a device, sign in
and enter your encryption password or the recovery key. mdbase stores your
key only in a form locked with your password, so it can’t reset the
password for you. The recovery key is how you get back in if you forget it.
For a Cloud copy collection, sign in on the new device and it downloads
the collection. For a Private collection, you also unlock it with your
encryption password or recovery key, or, in strict mode, approve it from
a device you already have. See
<a href="/security/#private-keys">Private collection keys</a> for how
this works.
</p>
<p>
If you’d prefer mdbase to store no copy of that key, turn on strict mode.
You then approve each new device from one you already have, by checking
that both screens show the same six-digit code.
</p>
<p>
If you lose a device, remove it from your account. The collection gets a
new key, so the removed device receives no further changes. It keeps the
files it already had.
</p>
</section>

<section class="content-section" aria-labelledby="apps">
<h2 id="apps">Apps ask first</h2>
<p>
An app asks for access to one collection and lists the operations it
needs, such as finding, creating and editing records. You choose the
collection and see what the app asks for before you approve it.
</p>
<p>
The permission is recorded with the collection, and every copy checks it:
your devices and, for Cloud copy, mdbase’s copy. In a Private collection,
a new permission takes effect once one of your signed-in devices has
recorded it. You aren’t asked again on the device.
</p>
<p>
You can narrow or revoke a permission at any time. Removing an app
never removes the collection, and your other apps keep using it.
If you lose a device, remove it from your account. It receives no further
changes but keeps the files it already had.
</p>
</section>

Expand Down Expand Up @@ -123,44 +137,6 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
</p>
</section>

<section class="content-section" aria-labelledby="moving-from-the-connector">
<h2 id="moving-from-the-connector">If you used Connect before</h2>
<p>
Existing accounts move to the new sync system automatically, in waves.
You don’t need to export anything, and your files stay where they are.
</p>
<ul>
<li>
<strong>Collections hosted by Connect</strong> become Cloud copy
collections, with their records, files, record IDs and members. Folders
that mirrored them join the new collection once the desktop app is
updated. Edits that weren’t uploaded yet arrive then, or are held for
review if the record also changed elsewhere.
</li>
<li>
<strong>Local collections served by the Connector</strong> become
Private collections when the updated <a href="/downloads/">desktop app</a>{" "}
takes them over on that computer. They keep their files, record IDs
and app permissions, and they’re end-to-end encrypted, so mdbase can’t
read them. Keep that computer online while it moves them.
</li>
<li>
<strong>Apps</strong> need their current versions. Older versions can’t
reach migrated collections and will ask you to update, and you may need
to approve some apps again.
</li>
<li>
<strong>Notes larger than 1 MiB</strong> move too. They stay as
Markdown files but aren’t in the normal record index, so they may not
appear in app lists or searches.
</li>
</ul>
<p>
mdbase keeps the old system’s copy of each collection for 90 days after
it moves, for recovery.
</p>
</section>

<section class="content-section" aria-labelledby="get-started">
<h2 id="get-started">Get started</h2>
<p>
Expand All @@ -170,5 +146,10 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
existing account. See the <a href="/apps/">apps</a> that work with mdbase
collections.
</p>
<p>
Building an app? <a href="/sdk/connect-quickstart/">Connect a browser
app</a> walks through sign-in, choosing a collection and working with
records using the <a href="/sdk/">SDK</a>.
</p>
</section>
</BaseLayout>
18 changes: 0 additions & 18 deletions src/pages/downloads/index.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,24 +116,6 @@ const releaseSize = (bytes: number) => `${Math.round(bytes / 1_000_000)} MB`;
</p>
</section>

<section class="content-section" aria-labelledby="updating-heading">
<h2 id="updating-heading">Updating from the Connector</h2>
<p>
Install this release over your existing copy. When your account moves to
the new sync system, the app takes over the collections the Connector
served and turns them into Private collections. Their files, record IDs
and app permissions carry over. Folders that mirrored a collection stored
by Connect join its Cloud copy.
</p>
<p>
On a headless install, <code>mdbase migrate status</code> shows progress
for each collection, and <code>mdbase migrate start</code> runs or
resumes the takeover. See{" "}
<a href="/connect/#moving-from-the-connector">if you used Connect before</a>{" "}
for what changes.
</p>
</section>

<section class="content-section" aria-labelledby="verify-heading">
<h2 id="verify-heading">Release details</h2>
<p>
Expand Down
2 changes: 1 addition & 1 deletion src/pages/index.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ easier to understand.</code></pre>
</div></section>
<section id="start" data-index="Get started" class="chapter" data-scene="intro" aria-label="Get started"><div class="chapter__inner">
<h2>Get started</h2>
<p>Sign up for mdbase Connect, the account that syncs and shares your collections. Your account starts with a small Cloud copy collection that you can open in any app. To sync a folder on your computer, as Cloud copy or Private, use the desktop app.</p>
<p>Sign up for mdbase Connect, the account that lets apps use your collections, and syncs and shares them. Your account starts with a small Cloud copy collection that you can open in any app. To sync a folder on your computer, as Cloud copy or Private, use the desktop app.</p>
<div class="chapter__actions home-actions"><a class="home-action home-action--primary" href="https://connect.mdbase.dev/signup">Sign up</a><a class="home-action" href="/downloads/">Download the desktop app</a><a class="home-action" href="/apps/">See all apps</a></div>
<p class="developer-note">Building an app? Any app can work with an mdbase collection. Read the <a href="/sdk/">SDK documentation</a> and the <a href="/spec/">specification</a>. The specification, Connect, Reader and Writer are open source under the MIT licence, <a href="https://github.com/mdbase-dev">on GitHub</a>.</p>
</div></section>
Expand Down
Loading