mdenc

mdenc is an innovative tool designed for encrypting Markdown documents while maintaining diff-friendly capabilities within git repositories. This project allows users to securely store private documentation without compromising the ability to see what has changed between edits.

Key Features

• Granular Encryption: mdenc encrypts content at the paragraph level. This means editing a single paragraph only alters that specific section in the encrypted output, preserving the ease of tracking changes in a git log or during pull request reviews.

• Transparent Integration: With native git support for smudge/clean filters, mdenc seamlessly encrypts Markdown files while allowing users to work with plaintext locally. The process is straightforward — simply mark directories for encryption, and mdenc handles the rest.

• Live Demo and Documentation: Explore a live demo or refer to the in-depth documentation for detailed specifications and security practices.

Example Workflow

To demonstrate its functionality, consider the following scenario where internal meeting notes are encrypted:

# Meeting Notes

Discussed the Q3 roadmap. We agreed to prioritize the mobile app rewrite.

## Action Items

Alice will draft the technical spec by Friday.  
Bob is handling the database migration plan.

## Budget

Total allocated: $450k for the quarter.

After running the command mdenc encrypt notes.md -o notes.mdenc, the notes become:

mdenc:v1 salt_b64=1z94qTI8... file_id_b64=eLP+c5cP... scrypt=N=16384,r=8,p=1
...

You can easily identify changes using git diff, where only altered paragraphs result in a modified line, allowing clearer version control without complete file changes.

Use Cases

mdenc is ideal for teams looking to protect internal documentation, including:

• Internal process documentation
• Onboarding guides
• Environment setup instructions
• Team contact information

However, it is important to note that mdenc is not intended to safeguard high-value secrets. The encryption method is designed for environments where content should not be publicly readable but does not warrant the robust safeguards required for sensitive information. For managing real secrets, a proper secrets management tool should be used.

Understand the Trade-Offs

While mdenc ensures some security by obscuring Markdown content, it does not offer forward secrecy or password rotation features. Observers can glean certain metadata about the document, such as paragraph counts and sizes, but the content itself remains encrypted and confidential. Review the SECURITY.md document for an extensive overview of the threat model and design choices.

By choosing mdenc, users benefit from a systematic approach to managing sensitive markdown content in a way that is both secure and easy to track changes.