SourceDraft is a free, open-source Git-based CMS for Markdown and MDX publishing. You write in the browser with a Tiptap editor and slash commands, upload images, run content QA checks, preview the generated file, and publish to a Git repository or remote CMS (WordPress, Ghost).
Licensed under AGPL-3.0-or-later.
Project status: SourceDraft is an early local/private MVP for Git-backed Markdown and MDX publishing. It is usable for solo writing and GitHub commits, but it is not a hosted CMS, multi-user product, or finished SaaS. See docs/project-status.md and CHANGELOG.md.
SourceDraft began as an internal tool for QuBrite.com and is published here for anyone running a similar static-site workflow. QuBrite is the origin story, not a dependency — you point SourceDraft at your own repository and config.
 |
 |
More views (toolbar, autosave, media library, content quality, preview, setup health): docs/screenshots.md. Regenerate with pnpm screenshots:generate.
SourceDraft is not WordPress and not a hosted website builder. It is a local Studio (editor) plus a small publish API that commits content and media to your target — GitHub, GitLab, Bitbucket, WordPress, or Ghost.
Your static site still builds and deploys exactly as before. SourceDraft creates or updates .mdx or .md files (via adapters) in the folder you configure, or pushes posts to a remote CMS API. Images can commit to your repo, upload to Cloudinary, or (experimentally) target S3-compatible storage.
Bloggers and writers on Git-backed static sites who want one place to draft posts without hand-editing frontmatter and Git commands.
Developers who want a shared article schema, Markdown/MDX adapters, and room to add more publishing targets later.
Not a fit yet if you need hosted multi-user accounts, OAuth, or a built-in site generator in this repository.
- Edit articles in Studio with a Tiptap rich editor, slash commands, and source mode for raw Markdown/MDX
- List and edit existing posts from your GitHub
contentDir - Validate fields against a universal article schema
- Content QA — non-blocking warnings for SEO, alt text, headings, links, and body length
- Publish checklist — validation status, output path, publish mode, and warnings before publish
- Preview Markdown or MDX adapter output and target file path before publishing
- Publish to Git hosts (GitHub, GitLab, Bitbucket) or remote CMS APIs (WordPress, Ghost)
- GitHub PR publishing — direct commit, pull request, or draft pull request for protected branches
- Upload images to git
mediaDir, Cloudinary, or (experimental) S3-compatible storage - Optional deploy hooks after publish (Vercel, Netlify, Cloudflare Pages, generic)
- Setup detection — scan local project files and suggest adapter, content, and media paths
- Content audit — read-only scan of existing posts (frontmatter, duplicate slugs, complex MDX)
- Configure paths, adapter, and categories in
sourcedraft.config.json - Protect Studio with a server-side admin password
- Demo mode — explore Studio with sample posts without GitHub credentials
- Setup health — Settings panel checks for missing config (no secrets exposed)
- Host your website or run your Astro build
- OAuth, user accounts, or role-based access
- Full S3/R2 media upload (
s3-compatiblevalidates config only; use Cloudinary or git media today) - Post list in Studio for Bitbucket, WordPress, and Ghost publishers
- OAuth, team accounts, or hosted multi-tenant Studio
Eight adapters ship today — see docs/adapters.md. See docs/project-status.md for the full shipped vs experimental list.
- You finish a valid article in Studio and click Publish.
- The publish API (server only) validates the article again.
- The configured adapter builds the file (YAML frontmatter + body) as
.mdxor.md. - The configured publisher sends content to your target — Git file commit or remote CMS API.
- For Git publishers, your CI or build step picks up the new file from
contentDir.
API tokens never reach the browser. They are read from .env on the server when you publish or upload media.
Details: docs/publishers.md · docs/git-publishers.md · docs/wordpress.md · docs/ghost.md
Compatibility (summary)
| Adapters (8) | Publishers (5) | Media (3) | Deploy hooks (4) | |
|---|---|---|---|---|
| Shipped | Astro MDX, Markdown, Next.js MDX, Hugo, Eleventy/Jekyll, Docusaurus, MkDocs, Nuxt Content | GitHub, GitLab, Bitbucket, WordPress, Ghost | Git repo, Cloudinary, S3-compatible† | Generic, Vercel, Netlify, Cloudflare Pages |
| Notes | Plugin loader for custom adapters | Git: list posts (GH/GL); Bitbucket publish only; WP/Ghost API publish | †S3 upload not implemented yet | Optional DEPLOY_HOOK_URL after publish |
Full matrices: adapters · publishers · media · deploy-hooks · quickstart recipes
Requirements: Node.js 22+, pnpm 11+
git clone https://github.com/bnz183/SourceDraft.git
cd SourceDraft
pnpm install
pnpm setup # guided wizard — or copy example files manually (below)Or copy example files manually:
cp sourcedraft.config.example.json sourcedraft.config.json
cp .env.example .envEdit .env:
SOURCEDRAFT_ADMIN_PASSWORD=choose-a-local-password
GITHUB_TOKEN=your-github-token
GITHUB_OWNER=your-github-username-or-org
GITHUB_REPO=your-site-repoStart Studio (UI + publish API):
pnpm devSign in, click New post, preview the output, publish. The file lands at contentDir/<slug>.mdx or .md depending on your adapter (default: src/content/blog/).
Try without GitHub: set SOURCEDRAFT_DEMO_MODE=true in .env, or leave GitHub vars empty and click Explore demo mode on the sign-in screen. Demo content reloads from repository fixtures on each API start. See docs/demo-mode.md.
Validate config: pnpm validate:config · Wizard details: docs/setup-wizard.md · Full walkthrough: docs/getting-started.md
If someone technical already installed SourceDraft and pointed it at your blog repository, you only need:
- The Studio address (usually
http://localhost:5173on their machine) - The admin password they set in
.env - Your site’s category list (from
sourcedraft.config.json)
Then: sign in → open a post from the Posts sidebar, or click New post → fill in title, description, category, tags, and body → upload images if needed → check the preview → Publish to GitHub. Your post appears as a file in the blog repo; the normal site build deploys it.
You do not edit GitHub by hand or run terminal commands for each post. If publish is disabled, ask your technical contact to check .env (GitHub token and repo) and that Studio is running with pnpm dev.
Plain-language guide: docs/non-technical-overview.md
MVP password auth is intended for local/private use. Do not expose Studio publicly without HTTPS, stronger auth, and deployment hardening.
Details: docs/security.md
sourcedraft.config.json |
.env |
|
|---|---|---|
| Purpose | Project settings safe to commit | Secrets and private targets |
| Examples | contentDir, mediaDir, publicMediaPath, categories, adapter |
GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, SOURCEDRAFT_ADMIN_PASSWORD |
| Shared in git? | Yes (copy from sourcedraft.config.example.json) |
Never |
Optional env vars (CMS_CONTENT_DIR, CMS_MEDIA_DIR, CMS_PUBLIC_MEDIA_PATH, CMS_ADAPTER, etc.) can override values from the JSON file. Secrets always stay in .env.
mediaDir is where images are committed in your site repo. publicMediaPath is the URL path Studio inserts into posts (for example /images).
Reference: docs/configuration.md
examples/astro-blog/ is a folder layout example — not a runnable Astro site. It shows where files go, a sample published .mdx, and matching config. Read its README before copying paths into your own blog repo.
Issues and pull requests are welcome. Read CONTRIBUTING.md for local setup, commands, and security reminders.
- Getting started
- Quickstart recipes — Astro+GitHub, Hugo+GitLab, WordPress, Cloudinary, deploy hooks, …
- Plugins
- SEO fields
- Demo mode
- Non-technical overview — for writers
- Publishers overview
- Git publishing (GitHub, GitLab, Bitbucket)
- WordPress publishing
- Ghost publishing
- Deploy hooks
- GitHub publishing
- GitHub PR publishing
- Editor and source mode
- Setup detection
- Content QA
- Media uploads
- Configuration
- Astro integration example
- Architecture
- Adapters
- Project status
- Manual acceptance test
- Smoke tests (Playwright)
- Release checklist
- Security
- Screenshots guide
- Changelog