What Markdown Obfuscation Actually Means
Markdown is plain text. It is designed to be readable, editable, and portable. Unlike JavaScript or CSS, there is no execution model, no control flow, and no syntax to scramble. This means "Markdown obfuscation" cannot mean what it means for code.
Two transformations are genuinely possible without breaking the format:
- Zero-width steganography — hide data invisibly in Unicode characters that render as nothing. The visible Markdown is unchanged; the hidden payload travels with the text.
- Base64 block encoding — replace readable paragraphs with Base64-encoded code blocks. The rendered output changes (prose becomes an unreadable Base64 string), and the transformation is fully reversible.
This tool implements both, plus the corresponding decoders. Every mode is verified by a round-trip test that decodes the output and compares it byte-for-byte to the original.
The Five Modes
| Mode | What Changes | Rendered Output | Reversible? |
|---|---|---|---|
| 🔒 Zero-Width Hide | Invisible Unicode characters inserted after the first word | Unchanged | ✅ Via Zero-Width Decode |
| 🔓 Zero-Width Decode | Extracts the hidden zero-width payload | N/A | N/A |
| 🧹 Zero-Width Clean | Removes every zero-width character | Unchanged (just cleaned) | N/A |
| 📦 Base64 Encode | Paragraphs replaced with Base64 code fences | Prose becomes Base64 text | ✅ Via Base64 Decode |
| 📥 Base64 Decode | Decodes Base64 code fences back to prose | Restored to original | N/A |
How Zero-Width Steganography Works
Unicode contains several characters that occupy zero visual width — they render as nothing. The four most commonly used for steganography are:
| Character | Unicode | Role |
|---|---|---|
| Zero-Width Space (ZWSP) | U+200B | Binary 0 |
| Zero-Width Non-Joiner (ZWNJ) | U+200C | Binary 1 |
| Zero-Width Joiner (ZWJ) | U+200D | Start marker |
| Word Joiner | U+2060 | End marker |
Each byte of the secret text is converted to 8 bits. Each bit is mapped to a zero-width character. The resulting invisible string is inserted into the Markdown — after the first word of the document. The decoder does the reverse.
How Base64 Block Encoding Works
Base64 block encoding is a visible transformation. It replaces readable paragraphs with a code fence containing Base64-encoded text:
Before: This release includes several improvements to the core engine. After: ```mdobf:b64 VGhpcyByZWxlYXNlIGluY2x1ZGVzIHNldmVyYWwgaW1wcm92ZW1lbnRzIHRvIHRoZSBjb3JlIGVuZ2luZS4= ```
The rendered Markdown now shows a Base64 string instead of the original prose. A reader without the decoder cannot see the content. The decoder reverses it byte-for-byte.
This mode is safe for Markdown structure because it uses a code fence with a custom language tag. Headings, lists, tables, links, images, blockquotes, HTML blocks, and inline code are never encoded — only plain prose paragraphs qualify.
What This Tool Cannot Do
- It cannot encrypt. Both modes are reversible encodings. Anyone with a decoder can recover the content.
- It cannot hide secrets from a determined reader. Base64 is trivially decoded; zero-width is trivially extracted.
- It cannot survive every platform. Gmail, Slack, Discord, and Twitter strip zero-width characters. Test first.
- It cannot make Markdown unreadable at the rendered level while keeping it byte-identical. Either the rendered text changes (Base64 mode) or the source gains invisible characters (zero-width mode).
Fenced Code Block Protection
Markdown fenced code blocks (``` and ~~~) contain literal content that must not be altered. Every mode in this tool tracks fence state and never touches content inside a fence.
Inline code spans (`code`) are also preserved. Base64 block encoding skips paragraphs that contain inline code, links, images, or that begin with Markdown structural markers.
Round-Trip Validation
Every operation ends with a round-trip test:
- Zero-Width Hide: the tool re-extracts the payload and verifies it matches the original secret exactly. It also verifies the visible text is byte-identical.
- Base64 Encode: the tool decodes the output and compares it to the original Markdown byte-for-byte. If the decoded Markdown does not match, the tool refuses to show success.
The results panel shows Round-trip PASSED or Round-trip FAILED with the reason. No silent failures.
When to Use Zero-Width Mode
- Watermarking generated documents — embed a provenance ID that survives copy-paste.
- Content attribution — tag CMS-rendered fields with the document and revision ID.
- Canary tokens — send the same text to N recipients with N distinct IDs; if the text leaks, the ID identifies the source.
- A/B test tracking — tag visible content with the experiment variant.
When to Use Base64 Mode
- Shipping Markdown previews — you want readers to see a scrambled block, not the actual prose.
- Staging content — draft content that should be decoded only at render time.
- Content gating — encode part of a document that should only be readable with a decode step.
- Educational examples — demonstrate Base64 encoding with real Markdown.
When NOT to Use Either Mode
- Never for secrets. Neither mode provides cryptographic protection.
- Never for legal signatures. Both can be stripped or forged.
- Never as a substitute for encryption. If confidentiality matters, encrypt first with
gpgorage, then apply a Markdown mode.