Open-Source CMS · waynesutton

markdown-site

markdown-site is an open-source publishing framework that lets developers write content in markdown files, sync them to a live site via CLI commands, and automatically make that content available to web browsers, LLMs, and AI agents. It uses Convex for real-time data synchronization and includes features like semantic search, admin dashboards, and knowledge base management.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/waynesutton/markdown-site

621

GitHub stars

Forks

TypeScript

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	waynesutton/markdown-site
Owner	waynesutton
Primary language	TypeScript
License	MIT — OSI-approved
Stars	621
Forks	91
Open issues	0
Latest release	Unknown
Last updated	2026-05-20
Source	https://github.com/waynesutton/markdown-site

What markdown-site is

Built with TypeScript, React 18, and Vite, markdown-site syncs markdown content from local `content/` directories to a Convex backend using CLI commands (`npm run sync`). It supports self-hosted or Netlify deployment, includes MCP server integration for AI tools, and provides REST APIs, RSS feeds, and a virtual filesystem interface (`/vfs/exec`) for content discovery and access.

Quickstart

Get the markdown-site source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/waynesutton/markdown-site.git2cd markdown-site3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

AI-native documentation and knowledge bases

Purpose-built for LLM discovery with `/llms.txt`, AGENTS.md, CLAUDE.md, and MCP server support. Ideal for projects that want their docs queryable by both humans and AI agents simultaneously.

File-based content workflows with version control

Markdown files live in git; no database lock-in. Developers can commit, review diffs, and rollback content like code. Supports multi-developer sync with instant browser updates via Convex.

Lightweight publishing for developers and technical teams

Minimal deployment friction (fork template, `npm run sync`, deploy). Built-in admin dashboard, real-time sync, and no rebuild cycle make it suitable for blogs, docs, and team wikis that update frequently.

Implementation considerations

Requires Node.js 18+ and Convex account (free tier available). Setup involves `npx convex dev`, fork configuration via `fork-config.json`, and one-time deployment step (`npm run deploy`).
Content workflow assumes developers are comfortable with markdown, git commits, and CLI commands. The `npm run sync` pipeline pushes local markdown to Convex; rollback and versioning rely on git history.
Self-hosting via Convex self-hosting requires Docker and infrastructure familiarity. Default path is Convex-managed deployment; Netlify legacy mode exists but is not the recommended path.
Real-time sync across browsers depends on Convex uptime and WebSocket connectivity. Virtual filesystem (`/vfs/exec`) has no auth by default; sensitive content exposure risk if deployed publicly.
Admin dashboard includes anonymous demo mode (30-min reset). Production security posture depends on correct auth mode configuration (`convex-auth`, `workos`, or `none`).

When to avoid it — and what to weigh

High-volume, non-technical content management required — No WYSIWYG editor; editing workflow is markdown + CLI + git commits. Better suited for developers than non-technical content teams.
Zero external dependencies or vendor lock-in concerns — Hard dependency on Convex (either managed or self-hosted). Not suitable if you require a fully independent, zero-external-service architecture.
Mature, battle-tested ecosystem needed immediately — Project created 2025-12-14 with no released versions yet. Latest push 2026-05-20 indicates active development, but production stability not yet proven. Early-stage tooling with limited community adoption history.
Strict license compliance for proprietary commercial use — MIT license is permissive, but commercial use requires verification of all transitive dependencies (Convex, React, etc.). Review dependency licenses before shipping to production.

License & commercial use

Licensed under MIT (MIT License). Permissive open-source license allowing commercial use, modification, and distribution with attribution. No restrictions on proprietary forks.

MIT license permits commercial use without restriction. However, dependencies (React, Vite, Convex, TypeScript, etc.) carry their own licenses; verify transitive dependencies comply with your commercial terms before production deployment. No commercial support, SLA, or indemnification from the project is documented.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	Medium

Security considerations

Virtual filesystem endpoint (`/vfs/exec`) has no authentication by default, exposing site content to unauthenticated `ls`, `cat`, `grep`, `tree` operations. Admin dashboard requires auth configuration; mode selection (convex-auth, workos, none) determines whether anonymous access is possible. Convex backend security depends on Convex platform; self-hosting requires operator hardening. No security audit or threat model documented.

Alternatives to consider

Astro or Next.js static site generation

Mature, file-based publishing with git-native workflows. Require rebuild/redeploy; no real-time sync. Larger ecosystem, more community examples. No native LLM discovery features.

Obsidian Publish or Notion

GUI-first content management with no code required. No git version control or developer workflows. Obsidian Publish is file-based; Notion is cloud-only. Neither optimized for AI agent discovery.

Mintlify or Gitbook

Purpose-built technical documentation platforms with GUI editors and git sync. Mature, battle-tested for docs. Less developer-focused than markdown-site; limited AI agent integration features.

Software development agency

Build on markdown-site with DEV.co software developers

Fork markdown-site on GitHub, run `npm run sync`, and deploy your docs or blog instantly. No rebuild cycle. LLM-ready by default.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

md markdownify-mcp tinacms

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source CMS AI Application Development Web App Development Cloud Deployment Talk to DEV.co

markdown-site FAQ

Do I need to rebuild or redeploy after updating markdown?

No. Run `npm run sync` (dev) or `npm run sync:prod` (prod). Convex syncs content in real-time; browsers update automatically. No build cycle.

Can I use this for a team or multiple developers?

Yes. Multiple developers can run `npm run sync` from different machines. Convex handles real-time synchronization. Content is versioned in git.

Is this suitable for large-scale production sites?

Unknown. No performance benchmarks, load test data, or production deployment case studies provided. Early-stage project (created 2025-12-14, no stable release). Suitable for small to medium sites; larger deployments require Convex scaling review.

Can I self-host without Convex?

No. Convex is a hard dependency. You can self-host Convex (requires Docker and infrastructure), but you cannot replace it. Legacy Netlify mode exists but is not recommended.

Software developers & web developers for hire

From first prototype to production, DEV.co delivers software development services around tools like markdown-site. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source cms and beyond.

Ready to ship content faster?

Fork markdown-site on GitHub, run `npm run sync`, and deploy your docs or blog instantly. No rebuild cycle. LLM-ready by default.

Talk to DEV.co Schedule a Consultation