TheDecipherist

TheDecipherist / markdownai

Public

MarkdownAI - live documents powered by directives

32
5
89% credibility
Found May 19, 2026 at 32 stars -- GitGems finds repos before they trend. Get early access to the next one.
Sign Up Free
AI Analysis
TypeScript
AI Summary

MarkdownAI is an open-source tool that transforms static documentation into live, data-driven documents. By adding a special `@markdownai` header to any markdown file, you unlock a set of directives that execute at render time - fetching real values from environment variables, databases, HTTP APIs, and shell commands. The toolchain includes a command-line interface for rendering documents, a Model Context Protocol (MCP) server for AI assistant integration, and a VS Code extension providing live preview and development support. Security is built-in with filesystem confinement, shell execution restrictions, HTTP request controls, and database query jailing - all operations are blocked by default and require explicit opt-in. The project is a well-structured TypeScript monorepo with comprehensive test coverage (754 tests), MIT licensing, and detailed documentation.

How It Works

1
📝 You write a special markdown file

You start a document with a special marker that tells the tool to make it alive and dynamic.

2
🔗 You connect your data sources

You add simple commands to pull in real information from your project - current branch name, database counts, API status, environment settings.

3
✨ Your documentation becomes real-time

Instead of typing values that go stale, your docs now fetch live data every time someone reads them. Your database count is always current.

4
🤖 You connect an AI assistant

You set up a simple connection so your AI helper can read your live documents and always see the current state of your project.

5
You choose how to view your docs
👁️
Live preview in editor

See your document update automatically as you write, with all values resolved in real-time

📄
Render to shareable file

Generate a clean static document you can commit to your repo or send to anyone

6
🔒 Everything stays secure

The tool locks down access by default - your docs can only read what you explicitly allow, keeping sensitive data protected.

✅ Your documentation can never lie again

Your team always sees accurate, up-to-date information. No more outdated screenshots or stale status reports.

Sign up to see the full architecture

5 more

Sign Up Free

Star Growth

See how this repo grew from 32 to 32 stars Sign Up Free
Repurpose This Repo

Repurpose is a Pro feature

Generate ready-to-use prompts for X threads, LinkedIn posts, blog posts, YouTube scripts, and more -- with full repo context baked in.

Unlock Repurpose
AI-Generated Review

What is markdownai?

MarkdownAI turns static `.md` files into live documents that pull real data at render time. Drop `@markdownai` on the first line of any markdown file, add directives like `@env`, `@db`, `@http`, or `@query`, and running `mai render` produces output with current branch names, live database counts, actual HTTP responses, or real shell command output. No more stale documentation. The tool ships as a CLI (`mai`), a TypeScript library, and an MCP server so AI tools like Claude and Cursor can read your documents and see live data instead of hardcoded values that went stale last week.

Why is it gaining traction?

The pitch is simple and visceral: your docs stop lying. Every team has documentation that was accurate once and is misleading now. MarkdownAI attacks this at the source by making documentation a function of the system state rather than a snapshot. The security model is thoughtful too -- shell execution, HTTP requests, and database queries are all jailed by default, which matters when you're putting directives in CI pipelines. The AI-native output mode (`--format=ai`) strips decorative formatting to reduce token consumption by up to 35%, which is practical for teams using Claude or Cursor heavily.

Who should use this?

Backend engineers writing runbooks that need to reflect actual system state. DevOps teams who want deployment checklists that query real endpoints instead of assuming health. AI-assisted developers who want their assistants reading documents that stay current. Teams adopting MDD (Manual-Driven Development) who need living artifacts instead of frozen markdown. If you write documentation about a system that changes, this is for you.

Verdict

The concept is sharp and the implementation is serious -- 754 tests across a six-package monorepo, a dedicated MCP server, and security-first architecture. At 32 stars it is early and unproven at scale. The credibility score of 0.8999999761581421% reflects that immaturity. If your team struggles with documentation staleness and you trust the security model enough to configure it, MarkdownAI is worth a serious look. Start with a single status document, not a company-wide rollout.

Sign up to read the full AI review Sign Up Free

Similar repos coming soon.