#User Guide

#URL Structure

All your content lives under your username namespace:

/@yourusername/document-slug-shortid
/@yourusername/collection-slug-shortid
/@yourusername/collection-slug-shortid/document-slug-shortid

The short ID (8 characters at the end) is the permanent identifier. The slug portion is human-readable but cosmetic — renaming a document changes the slug but not the short ID, so links are stable.

#The Editor

The split-pane editor (/new or via Edit on any document) has:

#Toolbar

Button	Shortcut	Action
B	Ctrl+B	Bold (**text**)
I	Ctrl+I	Italic (_text_)
S̶	—	Strikethrough (~~text~~)
H	—	Heading (## )
<>	Ctrl+K	Link ([text](url))
`	—	Inline code
```	—	Code block
•	—	Bullet list
1.	—	Numbered list
>	—	Blockquote
—	—	Horizontal rule
↑	—	Import .md file

• Ctrl+S saves the document
• Tab inserts 4 spaces
• The preview pane scrolls in sync with the editor

#Frontmatter

YAML frontmatter between --- fences is parsed and stored:

---
title: My Document
author: Jane
tags: [markdown, docs]
---

# Content starts here

Frontmatter is extracted but not rendered — it’s available via the API in the frontmatter field.

#Documents

#Creating

• Editor — click + New in the header
• Upload — go to /upload, drop a .md file
• Bulk Upload — drop multiple files at /upload (Bulk Upload tab)
• API — POST /api/documents

#Visibility

Level	Who can see	In search
Public	Anyone	Yes
Unlisted	Anyone with the URL	No
Private	Only you	No

Change visibility in Document Settings (gear icon on the document page).

#Versions

Every save creates a new version. Versions are immutable — you can view any previous version:

/@yourusername/doc-slug-shortid/v/1
/@yourusername/doc-slug-shortid/v/2

The version switcher dropdown on the document page lets you browse versions.

#Expiration

Set an expiration date in Document Settings. Options: 7 days, 30 days, 90 days, 1 year, or a custom date.

• Expired documents return 410 Gone to anyone except the owner
• The owner sees the document with an “Expired” badge and can extend or remove the expiration

#Deleting

Delete a document from Document Settings > Danger Zone. Documents are soft-deleted (recoverable by an admin).

#Collections

Collections organize documents into ordered groups. A document can belong to multiple collections.

#Creating

• From the dashboard — click + New Collection
• From /collections — click + New Collection
• From /collections/create directly
• During bulk upload — choose “New Collection”

#Managing Documents

From the collection page:

• + New Document — opens the editor, new doc is auto-added to the collection
• Upload — opens upload page with the collection pre-selected
• Add Existing Document — dropdown to pick from your documents not already in the collection
• Edit / Settings / Remove — per-document actions on each row

#Encrypted Collections

When you enable encryption on a collection:

• All documents in the collection are encrypted
• Any document added to the collection is automatically encrypted
• Documents cannot have encryption disabled while in an encrypted collection
• Removing a document from an encrypted collection keeps it encrypted (decrypt manually via document settings)

#Encryption at Rest

MarkdownBin supports optional AES-256-GCM encryption for documents stored on disk.

#How It Works

• Each user gets a unique encryption key (generated on first use)
• Your key is encrypted with the server’s master key — dual-layer protection
• Encrypted files (.md and .html) are unreadable without both keys
• Decryption happens transparently at view time — no password prompt needed

#What It Protects Against

Encryption at rest protects against filesystem breaches — if someone gains access to the storage disk, encrypted documents are unreadable. It does not protect against server compromise where the attacker has access to both the database and the application key.

#Enabling

• Per-document — Document Settings > Encrypt at rest
• Per-collection — Collection Settings > Encrypt at rest (encrypts all docs)
• Account default — Settings > Defaults > Encrypt new documents by default
• Bulk — Settings > Security > Encrypt All Documents

Encrypted documents show a 🔒 icon in listings.

#Settings

Access settings from the header (click your username) or go to /settings.

#Profile

• Display Name — shown on your documents
• Username — determines your URL namespace (/@username). Changing it changes all your document URLs.
• Email — for login

#Password

Change your password (requires current password).

#Defaults

• Default Visibility — applied to new documents and collections when no visibility is specified
• Encrypt by Default — new documents are automatically encrypted

#Security

• View encryption stats (total / encrypted / unencrypted documents)
• Encrypt All Documents — one-click bulk encryption

#API Keys

Manage at /api-keys.

• Create — set a name, access level (Read Only / Read-Write / Full Access), and optional expiration
• Copy — the key is shown once at creation; copy it immediately
• Revoke — immediately invalidates the key

Use keys with Authorization: Bearer mb_yourkey in API requests. See the API Reference for endpoints.