Why Markdown Is the Best Format
for Storing Secrets

Storing secrets in markdown files sounds reckless. Markdown is plain text. Plain text is readable. Readable means insecure. That is the intuitive reaction, and it is wrong — because the format you store secrets in and the encryption you apply to them are two completely separate concerns. Choosing the right format makes your secrets more portable, more durable, and easier to manage. Here is why markdown wins.

The Problem with Proprietary Databases

Every major password manager stores your credentials in a proprietary format. 1Password uses a SQLite database wrapped in its own encryption layer. Bitwarden uses a JSON export format but stores data in a cloud database internally. KeePass uses .kdbx files — a custom binary format that requires a KeePass-compatible reader to open. LastPass stores everything server-side in a format you have never seen and never will.

These are all reasonable engineering decisions. But they create a dependency: your data only exists in a format that one specific application can read. If 1Password changes its database schema, you rely on them to migrate your data. If Bitwarden's server goes down, you rely on your most recent export. If KeePass stops being maintained, you rely on the open-source community to keep .kdbx readers working.

This is vendor lock-in for your most critical data. And most people do not realize it until they try to leave.

Why Plain Text Is an Advantage

Markdown is a plain text format. This means it has properties that no proprietary database can match:

• Grep works. You can search your entire vault with grep -r "DATABASE_URL" ~/vault/ and find every file that references that variable. Try doing that with a .kdbx file or a 1Password vault.
• Diff works. You can see exactly what changed between two versions of a file. Line-by-line, word-by-word. Git shows you a meaningful diff because the non-secret content is human-readable text, not binary gibberish.
• Version control works. Because files are plain text, Git can track, branch, merge, and resolve conflicts intelligently. Every edit to your credentials has a commit hash, a timestamp, and a message explaining what changed.
• Portability is inherent. A markdown file written in 2026 will be readable in 2046. No application required. No database migration. No import wizard. Open it in any text editor on any operating system. Your notes are immediately accessible. The encrypted blocks are base64 strings that any decryption tool can process.
• No migration required. If you switch tools, your files do not change. They are already in a universal format. The application reads them; it does not own them.

None of these properties are possible when your data lives inside an encrypted database that only one application can read.

The Surgical Encryption Approach

The objection to storing secrets in markdown is obvious: if the file is plain text, anyone who accesses it can read the secrets. This is where surgical encryption changes the equation.

Instead of encrypting the entire file (which destroys all the advantages of plain text), you encrypt only the sensitive parts. The concept is simple: a markdown file contains both context and credentials. The context — your headings, your explanations, your checklists — does not need encryption. The credentials do. So you encrypt the credentials and leave the context alone.

The result is a file that is 95% human-readable and 5% encrypted. You can open it in any text editor and understand what the document is about. You can search it, diff it, and version it. The only parts you cannot read without the decryption key are the actual secret values — and those are the only parts that need protection.

How Claspt Implements This

In Claspt, when you mark a block as a secret, the plain text value is encrypted using AES-256-GCM with a unique nonce and replaced with an enc:v1: prefix followed by the base64-encoded ciphertext. The encryption key is derived from your master passphrase using Argon2id with a high memory cost, making brute-force attacks impractical.

Here is what a file looks like on disk:

# AWS Production Environment

The region is ap-south-1 and the account ID is 123456789012. Connect through the Mumbai VPN endpoint first.

Access Key: enc:v1:aGVsbG8gd29ybGQ=...
Secret Key: enc:v1:dGhpcyBpcyBhIHRl...
RDS Password: enc:v1:ZW5jcnlwdGVkIGRh...

The region, account ID, VPN instructions, and all headings are plain text. You can search for "AWS Production" and find this file instantly. You can see in a Git diff that you added the VPN instruction last Tuesday. But the actual access key, secret key, and database password are opaque without your master passphrase.

A Real-World Example: The Deploy Runbook

Consider a deployment runbook. In a traditional password manager, you would have the deployment steps in a wiki or markdown file somewhere, and the credentials in 1Password. Every deployment, you switch between both. You copy, you paste, you verify you grabbed the right entry for the right environment.

In a markdown vault with per-block encryption, the runbook and the credentials live in the same file. Step 3 says "SSH into the production server" and the SSH key passphrase is right there, encrypted inline. Step 7 says "Run the database migration" and the database connection string is right there, encrypted inline. No context switching. No copying from one app and pasting into another.

When you update the runbook — adding a new step, changing a server address, rotating a password — the Git diff shows exactly what changed. The non-secret changes are readable in the diff. The secret changes show as updated enc:v1: blocks. You know that a credential was rotated even if you cannot see the old and new values in the diff.

The Portability Guarantee

The strongest argument for markdown is longevity. Every proprietary format eventually dies or changes. Evernote's .enex format has been through multiple breaking changes. OneNote's format is effectively undocumented. Even open formats like .kdbx require specialized software.

Markdown has been stable since John Gruber published the specification in 2004. It is the default format for documentation on GitHub, GitLab, and Bitbucket. It is the native format of static site generators, knowledge bases, and developer documentation. There are hundreds of editors that can read and write it. It requires no special software to open — Notepad, TextEdit, cat, or less will do.

If Claspt does not exist in ten years, your vault is still a folder of markdown files. Your notes are immediately readable. Your encrypted blocks are AES-256-GCM ciphertext with documented key derivation parameters — any competent cryptography library can decrypt them given your passphrase. You are not waiting for an abandoned open-source project to release a compatibility update. You are not hoping a company stays in business so you can access your own data.

Your secrets deserve better than a proprietary database. They deserve a format that will outlive the application that created them.