# Integrating with Marked

Marked Share was built to be the ideal cloud companion to [Marked](https://markedapp.com) for macOS. Instead of having to copy and paste text or manage file uploads through a web browser, Marked can communicate directly with your Marked Share account.

## One-Click Account Connection

Connecting Marked to your Marked Share account requires no manual API key generation or copy-pasting:

1. In Marked, trigger the Share workflow. Marked opens the authorization URL in your default web browser (`share.markedapp.com/auth/marked`).
2. Log in (or sign up) and click **Connect Marked**.
3. Marked Share mints an account **API Token** and a machine-specific **Device Key**, then triggers a deep link: `x-marked-3://login?api_token=...&device_key=...`.
4. Marked catches the link, securely stores the credentials in your macOS Keychain, and marks your machine as connected.

## Publishing from the macOS Desktop

Once connected, sharing a document from Marked is seamless:

- **Packaging:** Marked bundles your active document into a TextPack with all local referenced images and custom reading styles.
- **Upload:** The bundle is transmitted via the Marked Share API in a single HTTP request.
- **Instant Link:** Marked receives the published share URL (`markedb.in/...`) immediately, ready to copy to your clipboard or open in your browser.

## Concurrency and Conflict Avoidance

When you edit a document in your local editor and preview it in Marked, sharing it again updates the existing remote document rather than creating duplicates.

To prevent accidental data loss:

- Each version on the server has a unique `content_hash`.
- Marked sends an `If-Match` header with the last known hash.
- If the document was modified elsewhere (in the web editor or on another Mac), Marked Share returns a `409 Conflict`, naming the specific device that made the newer change.

## Syncing Reviews Back to Mac

When readers leave highlights and comments on your shared document, you can pull those reviews back into Marked. Marked imports the reader's `highlights.json` and displays their feedback directly over your local preview.