mdspec / blog
Specs, docs & AI.
Without the friction.
Practical writing for developers navigating the new reality of AI-speed codebases, markdown sprawl, and documentation debt.
Featured
All articles
Why AI Agents Need Your Specs in Git, Not Locked in a SaaS (And How to Serve Them from S3)
AI coding agents can't authenticate into your Confluence or Notion. They need specs at a URL they can reach. Here's the pattern for keeping a machine-readable copy current alongside your human-readable docs.
GitBook vs Mintlify vs mdspec: Which One Actually Solves the Spec Drift Problem?
GitBook and Mintlify are excellent tools — for external product docs. If you're trying to keep internal specs in sync across Confluence, Notion, and ClickUp, they solve a different problem. Here's a clear comparison.
Publish Markdown to Confluence with GitHub Actions in One Line: A 2026 Setup Guide
A plain comparison of every real option for syncing markdown from GitHub to Confluence — mark, markdown-confluence, duo-labs, and mdspec — with a complete working setup you can copy today.
mdspec in 5 Minutes: From Zero to Publishing Markdown on Every Merge
A screencast-style walkthrough: create a repo, add one .mdspecmap, add the GitHub Actions step, push a commit, see it appear in Confluence or Notion. Real YAML throughout.
mdspec vs Zapier and Make: Why a Purpose-Built Tool Beats a General One
Zapier and Make can connect almost anything to anything. So why use a dedicated tool like mdspec for syncing markdown specs? Because 'fits anything' is a tax you keep paying — and 'fits one thing perfectly' is the whole point.
The Engineering Manager's Playbook for Ending Documentation Debt
Documentation debt isn't a culture problem — it's an architecture problem. Here's a practical framework for eliminating it: who owns the spec, what enforces freshness, and how to make publishing automatic.
Why ClickUp Docs Goes Stale (And How to Sync Markdown from GitHub Automatically)
ClickUp's markdown support is broken by design, and every standard integration tool hits the same wall. Here's why — and the one pattern that actually works for syncing specs from GitHub to ClickUp Docs.
Notion's GitHub Integration Is Read-Only: 5 Workarounds for Actually Publishing Markdown from Your Repo
Notion's native GitHub integration can't push markdown content into Notion pages. Here are five real workarounds, ranked by how far they'll get you — with no hype about what each one actually can't do.
Spec-as-Code: Publishing One Markdown Source to Notion, Confluence, ClickUp, and S3 from a Single Repo
Spec-as-code is the missing layer between 'docs as code' and the reality of multi-tool engineering orgs. One markdown source in git. Automatic fan-out to wherever your team actually reads.