Every engineering team has the same problem. The spec lives in the repo — where it belongs — but S3, Confluence, Notion, or ClickUp is where the rest of the company goes to read it. So someone copies it over manually. Then the spec gets updated. Then it gets updated again. Three months later, you have two documents that contradict each other, and nobody knows which one is true.
mdspec fixes this with one line in your GitHub Actions workflow.
How It Works
Drop a .mdspecmap file in any folder in your repository. Add npx mdspeci publish --project to your CI pipeline. That's it.
Every time a spec merges to main, mdspec detects the changed markdown files, sends them through a delivery queue, and pushes the updated content directly into your connected tools — Notion, Confluence, or ClickUp — preserving your folder structure as a nested page hierarchy. Your repo stays the source of truth. Your docs tools stay current.
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: npx mdspeci publish --project proj_xxx
env:
MDSPEC_TOKEN: ${{ secrets.MDSPEC_TOKEN }}
That's the entire CI integration. No GitHub App to install. No OAuth permissions on your repo. No webhooks to maintain.
What Makes It Different
Most doc sync tools work by giving a third-party app read access to your entire repository and running a background sync. mdspec doesn't do that. Publishing only happens when you push — you're in control of when and what gets delivered. There's no background process polling your repo, no automatic mutations, no commits made on your behalf.
The CLI does one job: detect changed .md files via git diff, build a payload, and hand it off to the API. From there, a worker queue handles delivery with rate limiting, exponential backoff retries, and folder hierarchy resolution. Your CI job returns a 202 Accepted immediately — it doesn't hang waiting for Notion's API.
The result in your terminal looks like this:
✓ Published specs/payments/checkout-retry.md → Notion
✓ Published specs/auth/sso-setup.md → Confluence
— Skipped specs/old-spec.md (no changes)
Built for Engineering Teams
mdspec is designed around how engineering teams actually work:
Folder structure mirroring. Your repo hierarchy becomes a nested page tree in the target tool. specs/payments/checkout-retry.md becomes a page nested under payments/ in Notion — automatically.
Spec snapshots for AI context. Download the latest published version of any spec as a .md file directly from the dashboard. Pull it into Cursor, Windsurf, or Claude as coding context without needing a plugin or manual copy-paste from Confluence.
Page identity preservation. Specs are updated in-place on subsequent publishes — not deleted and recreated. Comments, reactions, and manual annotations in the target tool survive every update.
Team access controls. Org-level and project-level roles let you control who can publish, who can configure tokens, and who can only read.
Top comments (0)