The Marked Share API

Marked Share is built API-first. The same HTTP endpoints powering the Marked desktop app and the web frontend are available for your own scripts, Raycast extensions, Alfred workflows, and automated publishing pipelines.

Authentication and Endpoints

The API is located at https://share.markedapp.com/api/v1.

Requests require an API Token and write operations require an X-Device-Key header:

Authorization: Bearer <your_api_token>
X-Device-Key: <your_device_key>

Tokens and device keys can be created in your account settings.

Core Capabilities

1. Document Management

• List & Search: GET /documents?q=query&limit=25 supports full-text ranked search and pagination headers (X-Total-Count, Link).
• Create Documents: POST /documents accepts either raw JSON with body_markdown, title, visibility, and collection_slug, or multipart TextPack archives (.textpack / .zip).
• Update Documents: PATCH /documents/:id updates content safely with If-Match: <content_hash> optimistic concurrency locking.
• Export TextPacks: GET /documents/:id/textpack downloads the complete document bundle with images and metadata.

2. Highlight Sets and Reviews

• Retrieve Annotations: GET /documents/:id/highlight_sets lists all reader highlight sets on your documents.
• Import Highlights: POST /documents/:id/highlight_sets/:set_id/import merges a reviewer’s feedback into your personal highlight set.

3. Collections

• List Collections: GET /collections returns all collections, their display modes, and custom domains.
• Inspect Collection: GET /collections/:id?include=documents lists collection metadata and member posts.

4. Cross-Publishing

• Micro.blog: POST /documents/:id/microblog triggers immediate Micropub syndication with format: "full" or format: "excerpt".

Automating Your Workflow

Because Marked Share accepts standard Markdown over a clean REST API, you can easily integrate it into your existing tools:

curl -X POST https://share.markedapp.com/api/v1/documents \
  -H "Authorization: Bearer $MARKED_API_TOKEN" \
  -H "X-Device-Key: $MARKED_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "title": "My Post",
      "body_markdown": "# Hello World\nPublished via curl.",
      "visibility": "public",
      "collection_slug": "marked-share"
    }
  }'

With simple API primitives, you can publish from anywhere, script backups, and build custom workflows tailored to your writing habits.

Integrating with Micro.blog

For many writers, publishing on the web means participating in the open web and IndieWeb ecosystems. Marked Share includes native integration with Micro.blog, letting you cross-post documents directly from your library.

Connecting Your Micro.blog Account

Connecting Micro.blog takes just a few seconds:

1. Navigate to Settings → Micro.blog on Marked Share.
2. Paste in your Micro.blog App Token (generated from your Micro.blog Account settings).
3. Choose your default publishing format:
   • Full Text: Posts the entire document body as a standard blog entry.
   • Excerpt: Posts the title, a generated summary, and a direct link back to your canonical Marked Share document.
4. Save your token. Marked Share verifies the token and links your @username.

Publishing from Marked Share

Once connected, publishing to Micro.blog is available directly from the document toolbar and share dialog:

• Click Publish to Micro.blog on any document you own.
• Choose whether this specific post should be sent as Full Text or Excerpt.
• Submit the form. Marked Share formats the post, issues the Micropub request, and stores the resulting Micro.blog post URL.

Automatic Feeds and Discovery

Once published, your document displays a direct badge link to the Micro.blog post. If you are running a public Marked Share collection as a blog, changes also ping relevant endpoints to ensure feed readers and subscribers receive updates immediately.

Cross-posting long-form drafts or short notes to your personal Micro.blog timeline has never been easier.

Integrating with Marked

Marked Share was built to be the ideal cloud companion to Marked 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.

TextPack Import/Export

Portable file formats are essential for avoiding vendor lock-in. Marked Share embraces the open TextBundle and TextPack standards to keep your content self-contained and universally readable.

What is a TextPack?

A TextBundle is an open format that groups Markdown text and all associated assets into a single bundle folder. A TextPack is simply a compressed (zipped) TextBundle file with a .textpack extension.

Inside a Marked Share TextPack archive, you will find:

• text.md (or text.markdown): The complete, raw Markdown source.
• assets/: Embedded images referenced throughout the text (PNGs, JPEGs, GIFs, WebPs).
• info.json: Metadata specifying the Markdown dialect and published reading style preferences.
• highlights.json: Any highlights, notes, and signatures attached to the document.

Importing Documents

You can import documents into your Marked Share library at any time:

• Drag and Drop: Drag a .textpack, .zip, or .md file directly into your Library or upload area.
• Capture Web Pages: Use the Capture URL tool to convert an external web article into clean Markdown and assets automatically.
• Asset Handling: Local image paths are automatically parsed, uploaded to secure cloud storage, and updated to point to resilient hosted URLs.

Exporting and Round-Tripping

Every document published on Marked Share can be exported immediately:

• Click the TextBundle link in the document toolbar or share dialog.
• Download raw Markdown via /d/<id>.md.
• Download the complete asset-backed archive via /d/<id>.textpack.

Because Marked Share exports follow the standard TextBundle specification, you can open exported TextPacks in Marked, Ulysses, Bear, or any compatible editor with all images and reading styles completely intact.

Highlighting and Sharing

Most publishing tools treat readers as passive consumers. Marked Share turns every shared document into a collaborative review surface with built-in highlighting and margin notes.

Highlighting for Everyone

Anyone with permission to view a document can annotate it—no account or login required.

There are two easy ways to highlight:

1. Selection Menu: Select any string of text. A floating toolbar appears with options to Highlight or Comment.
2. Keyboard Shortcuts: Press h to toggle a highlight on the currently active block, or press c to attach a comment.

If you are doing a deep proofread, turn on Highlight as I select in the Highlights menu. Every selection you drag across will instantly become an active highlight without extra clicks.

Notes and the Comments Sidebar

When you attach comments to highlights:

• A speech-bubble indicator appears in the margin next to the annotated passage.
• The Comments Sidebar displays all notes in chronological order alongside the document.
• Clicking any note smoothly scrolls to its exact passage in the text.
• Notes and highlights save automatically in real time—no save buttons required.

Isolated Highlight Sets

Your annotations never overwrite anyone else’s. Every reader creates their own distinct Highlight Set.

When you share your annotations, Marked Share generates an annotated link with a ?hl=<id> query parameter. Anyone following that link sees the document with your specific highlights and comments overlaid.

The Reviews Panel for Authors

If you are the author of a document, you have access to the Reviews panel.

Here you can:

• See all highlight sets submitted by readers and editors.
• Inspect reader signatures and feedback in one consolidated view.
• Import selected review highlights directly into your own master highlight set.
• Export annotations to take them back into local tools.

Previewing Documents

Reading Markdown on the web should feel as deliberate and polished as reading a well-typeset book. Marked Share brings the previewing sensibilities of Marked right into the browser.

Guided Reading and Block Navigation

When viewing a document, Marked Share includes keyboard navigation and reading position tracking:

• Block Cursor: A subtle indicator tracks your active block as you read.
• Reading Band: Navigation automatically keeps your current reading position roughly one-third of the way down the screen, preventing fatigue from awkward scrolling.
• Persistent Location: Your exact reading place is saved locally in your browser. Reopening the document restores your place immediately.

Press ? on any document page to view the navigation shortcuts:

• j / k or ↓ / ↑: Move to the next or previous block.
• gg / t: Jump to the top of the document.
• G / b: Jump to the bottom of the document.
• Page Down / Page Up (or Ctrl-d / Ctrl-u): Page down or up while maintaining reading focus.
• e: Instantly jump into the editor (if you have permission).

Five Reading Styles

Typography can make or break long-form prose. Marked Share includes five distinct reading styles, each available in independent Light and Dark modes:

1. Editorial: Classic serif typography designed for long essays, articles, and documentation.
2. Manuscript: Traditional book-style formatting with generous margins and classic serif type.
3. Swiss: Clean, crisp grotesque sans-serif inspired by mid-century modern graphic design.
4. Contrast: High-contrast, sharp geometric type for maximum clarity and focus.
5. Typewriter: Monospaced aesthetic crafted for technical drafts, logs, and code-heavy notes.

The Typography Hierarchy

As an author, you can set a Published Style in the Share dialog to give your document an intended aesthetic.

However, readers always remain in control:

1. Reader’s per-document choice (selected in the Aa menu).
2. Reader’s global default (saved in settings or browser preference).
3. Author’s published style.
4. Default fallback (Editorial).

This balance ensures authors can suggest a tone while readers can always choose the typography that works best for their eyes.

Using the Editor

While Marked Share plays nicely with external Markdown editors via Marked and our API, it also features a built-in web editor designed for focused writing and fast edits.

The Web Editor

The editor is powered by CodeMirror, offering syntax highlighting and a distraction-free environment with standard keyboard shortcuts:

• ⌘B / Ctrl-B: Bold
• ⌘I / Ctrl-I: Italic
• ⌘E / Ctrl-E: Inline code
• ⌘K / Ctrl-K: Insert link
• Tab / Shift-Tab: Indent / Outdent list items and code blocks

As you type, changes are autosaved in real time with continuous feedback in the status bar.

Managing Images

You don’t need external image hosting to write rich documents. In the editor, click the Image icon to:

• Link to an external image URL with alt text.
• Upload local image files (PNG, JPEG, GIF, and WebP up to 5 MB each).

When you upload an image, Marked Share stores it securely with your document and inserts a scoped path (/d/:id/i/...) that automatically inherits the document’s visibility permissions.

Version History and Conflict Protection

Every time you save substantial changes, Marked Share records a snapshot in the document’s Version History. You can view past versions, see which device made each edit, and inspect visual diffs to track changes over time.

Marked Share also protects you against accidental overwrites. If you leave a tab open and edit the same document on your Mac in Marked or from another browser, the editor detects the newer revision and warns you: Updated elsewhere — refresh to continue. Your changes won’t silently clobber someone else’s work.

Remix and Duplicate

If enabled in your document settings, signed-in readers can click Duplicate to my account. This creates an independent clone in their own library—complete with all attached images—allowing them to remix, iterate, and build upon your shared drafts.

Publishing and Collections

Publishing a document in Marked Share is designed to give you precise control over who can read your work and how it is organized.

Visibility Levels

Every document in your library has one of three visibility settings:

1. Private (Default): Only you and authenticated API tokens on your account can access the document. Anyone else visiting the URL receives a strict 404 Not Found—not an authorization challenge—so the link never leaks that the document even exists.
2. Unlisted: Anyone with the link can view the document, but it will never appear on your public profile or in search engine listings.
3. Public: Anyone with the link can view the document, and you can optionally feature it on your public profile.

Link Formats and Protection

When you publish, Marked Share generates clean short links on markedb.in:

• Short Codes: markedb.in/x7k2m — quick 5-character slugs generated on publish.
• Custom Slugs: markedb.in/yourname/custom-slug — human-readable URLs tied to your profile handle.
• Raw Markdown: markedb.in/d/<id>.md — instant access to clean plain text.
• TextBundle Exports: markedb.in/d/<id>.textpack — zipped bundle containing the markdown and all embedded assets.

Need extra security? You can add password protection or an expiration date directly from the Share dialog. Password-protected documents require readers to enter a passphrase before unlocking, and expired documents gracefully return 404s after their deadline.

Collections: From Reading Lists to Full Blogs

A Collection is an ordered group of documents with its own landing page at markedb.in/u/yourname/c/collection-slug.

Collections can be displayed in two modes:

• List Mode: A clean, curated table of contents or documentation index where you can order articles up and down.
• Blog Mode: A reverse-chronological blog feed with full-text or summary post views, pagination, and an automatic Atom feed at /feed.xml.

You can even attach custom CNAME domains to collections, turning Marked Share into a lightning-fast Markdown blogging engine.

Introducing Marked Share

For years, Marked has been my playground for turning Markdown into beautifully rendered documents on macOS. But while previewing Markdown on your local machine is great, sharing those documents with clients, editors, or friends has always felt a little fragmented. You export to PDF, print to HTML, or paste text into a generic pastebin that ruins your formatting.

I built Marked Share to solve that problem.

Marked Share is a Markdown-native publishing and sharing platform designed from the ground up to pair with Marked (and with any plain-text workflow). It gives your Markdown documents stable, shareable links, gorgeous typography, and collaborative annotation tools without the weight or complexity of a traditional CMS.

The Idea Behind Marked Share

The core philosophy of Marked Share is simple:

• Markdown First: Your raw Markdown is preserved exactly as you wrote it. No hidden proprietary database locks, no mangled syntax.
• Apex Rendering Engine: Online documents are rendered with Apex, the same rendering pipeline powering Marked. If it looks great in Marked, it will look identical in your browser.
• Clean, Short Links: Your account, editor, and library live at share.markedapp.com, while published documents get clean, minimal share links on markedb.in.
• Fast, Private, and Free: No ads, no bloated trackers, no subscriptions. Documents are private by default until you decide to share them.

Whether you want to publish a quick public note, send a password-protected draft to a client, or publish a full blog with an Atom feed, Marked Share handles it with zero friction.

Over the next few posts, I’ll walk through everything Marked Share can do—from collections and typography styles to interactive annotations, TextPack bundles, and our API.