Open source · CI-native · Free forever

Keep writing markdown.
We'll automate the rest.

On every commit or merge, your markdown is published as living documentation — fully automated through a single step in your CI pipeline.

Get startedGitHubHow it works
publish pipeline

Your repository

markdown + frontmatter

GitHub Actions

npx mdspeci publish

mdspec

route · optional agent transform

Published

documentation, live

Notion
Confluence
ClickUp
S3

How it works

Three steps to automated publishing

1

Connect an integration

Sign up, create a project, and connect your integrations.

2

Add frontmatter to a spec

Add type and integration to any markdown file. Files without frontmatter are silently skipped.

3

Add the CI step

One line in your GitHub Actions workflow. Every push to main syncs changed specs.

Why your team needs it

Documentation that keeps pace with the code

Engineering teams don't need another docs tool. They need documentation that updates itself — automatically, on every push.

Decouple docs from your repository

As your project scales, markdown specs can quietly bloat your repository. mdspec offloads files directly to S3 on every push — keeping your codebase lean while your documentation stays versioned, accessible, and independently searchable.

Close the loop on agent-driven tasks

Pair agent templates with your spec files and every push becomes a trigger for structured automation. Release notes, task summaries, and ADRs are generated and published with no manual intervention — keeping your tools in sync with what you ship.

Integrations that scale without overhead

Keeping up with changing APIs across Confluence, Notion, and ClickUp is a maintenance burden your team shouldn't carry. mdspec handles rate limiting, retries, and guaranteed delivery so syncs stay safe and reliable.

Two files. Done.

Configuration that lives in your repo

Add four lines of frontmatter to any markdown file. Push to GitHub. It appears in Notion, ClickUp, Confluence, Jira, or S3 — automatically.

# docs/specs/checkout-retry.md
---
type: task
id: CU-182
---
# Checkout retry policy
# .github/workflows/mdspec.yml
- name: Publish specs
run: npx mdspeci publish --project ${PROJECT_ID}
env:
MDSPEC_TOKEN: ${{ secrets.MDSPEC_TOKEN }}
Heads up: the npm package is mdspeci (trailing i) — not mdspec. Running npx mdspec installs an unrelated third-party package and exposes your CI secrets to it.

Features

Built for how engineering teams actually work

Git-native

Change detection via git diff. Only modified specs are published. Distribution files live in the repo — version-controlled and easy to manage.

Opt-in per file

Only files with frontmatter sync. Skip a file by removing its frontmatter — no patterns, no allowlist.

One repo, any number of integrations

Map different folders to different tools — one team's specs go to ClickUp, another's to S3, all from the same repo.

Agent layer

Transform specs before publishing with built-in templates like task summaries and release notes.

Append-only publishing

Removing a file from the repo does not delete it from the target tool — mdspec only adds and updates.

Team-friendly

Each spec declares its own destination in frontmatter. Different teams ship to different tools from the same repo with zero shared config.

Under the hood

What happens between push and published

Here's the path from your git push to a published doc — including the optional agent step that transforms your markdown before it lands anywhere.

Click any step to see what's happening there.

Agent templates

Transform specs on the way out

Assign a template to any folder and the agent transforms your spec before it publishes — no prompting required.

Security & compliance

Built on compliant infrastructure

Hosted on Vercel (SOC 2 Type II certified, ISO 27001 compliant). mdspec does not currently hold its own certifications — the controls below describe our operational security choices.

SOC 2 Type II

Hosted on Vercel, which holds SOC 2 Type II certification covering security, availability, and confidentiality.

ISO 27001

Vercel's infrastructure is ISO 27001 certified, meeting the international standard for information security management.

Encrypted credentials

Integration credentials are encrypted at rest with authenticated encryption (XChaCha20-Poly1305) and keys held outside the application database.

No content storage

Spec content is never stored outside your compliant sources. It flows directly from CI to your target tool — only metadata is retained.

Powered by Claude Haiku

Agent template transformations run on Anthropic's Claude Haiku 4.5 — fast, cost-efficient, and built on enterprise-grade infrastructure.

Open source

Free forever. Built in the open.

mdspec is open source and free to use, self-host, and contribute to. No pricing tiers, no limits, no credit card required — ever.

View on GitHubStart publishing