Skip to main content

​
Welcome to Markdown-OS

Markdown-OS is a developer-focused markdown editor served from a local CLI. Edit in your browser with real-time preview, Mermaid diagrams, syntax highlighting, KaTeX math equations, and auto-save.

Installation

Get started with pip or uv in seconds

Quick Start

Open your first file or workspace

GitHub Repository

View source code and contribute

PyPI Package

Check latest release and stats

​
Why Markdown-OS?

Markdown-OS bridges the gap between simple text editors and heavyweight IDEs by providing a focused, browser-based markdown editing experience with professional features:

Live Preview

See your rendered markdown as you type with instant updates

Mermaid Diagrams

Create flowcharts, sequence diagrams, and state diagrams inline

Auto-Save

Never lose work with debounced auto-save and conflict detection

Syntax Highlighting

Beautiful code blocks with language detection and copy buttons

Math Equations

Render LaTeX equations with KaTeX for technical documentation

Workspace Mode

Manage multiple files with tabs, file tree, and smart navigation

​
Key Features

​
Single File Mode

Open a single markdown file with a clean, distraction-free interface: 
markdown-os open ./notes.md
Perfect for quick edits, personal notes, or focused writing sessions.

​
Directory Workspace Mode

Work with entire documentation projects using the folder mode: 
markdown-os open ./my-docs
Features include:
  • File tree sidebar with search
  • Multi-file tabs (up to 15)
  • Smart tab naming for duplicate filenames
  • URL-based file routing
  • Cached content and scroll positions per tab
The app automatically detects whether you’re opening a file or directory and switches modes accordingly.

​
WYSIWYG Editing

Edit markdown in a rich WYSIWYG editor powered by contenteditable with:
  • Inline shortcuts: Type **text** and it becomes bold automatically
  • Click-to-edit blocks: Code blocks, Mermaid diagrams, and math equations
  • Smart formatting: Heading shortcuts with #, list auto-continuation
  • Image paste/drop: Ctrl+V or drag images directly into the editor
  • Undo/redo history: Full editing history with keyboard shortcuts

​
Developer-Friendly Architecture

Backend

Python 3.11+ with FastAPI, Typer CLI, Uvicorn ASGI server, and Watchdog file monitoring

Frontend

Vanilla HTML/CSS/JavaScript with Marked.js, Turndown.js, Mermaid.js, KaTeX, and highlight.js

​
File Safety

Robust file handling ensures your content is always safe:
  • POSIX file locks: Shared locks for reads, exclusive locks for writes
  • Atomic writes: Content written to temp file → fsync → atomic replace
  • Conflict detection: Warns when external changes conflict with unsaved edits
  • WebSocket sync: Real-time notifications for external file changes
File locks use POSIX fcntl and are currently optimized for Linux/macOS. Windows compatibility may require adaptation.

​
Use Cases

​
Personal Knowledge Base

Build a local-first knowledge base with:
  • Quick capture of ideas and notes
  • Mermaid diagrams for system design
  • Code snippets with syntax highlighting
  • Math equations for technical notes

​
Documentation Projects

Author technical documentation with:
  • Multi-file workspace mode
  • Live preview for instant feedback
  • Table of contents generation
  • Image upload and management

​
Meeting Notes

Capture structured meeting notes with:
  • Task lists with checkboxes
  • Tables for action items
  • Inline links to related files
  • Auto-save to never lose content

​
Technical Writing

Write blog posts, tutorials, and guides with:
  • Rich formatting options
  • Code blocks with copy buttons
  • Mermaid diagrams for explanations
  • Export-ready markdown

​
What Makes It Different?

1

Local-First

No cloud dependencies, no accounts, no data leaving your machine. Your files stay on your filesystem.
2

Browser-Based

Runs in your browser but served from localhost. Get the benefits of web rendering without giving up control.
3

Developer-Focused

Built by developers, for developers. Syntax highlighting, Mermaid, KaTeX, and CLI-first design.
4

Zero Configuration

Install and run. No config files, no setup wizards, no dependencies beyond Python.

​
Technical Specifications

FeatureDetails
Python Version3.11+ (tested on 3.11, 3.12, 3.13)
Package Managerpip or uv
LicenseApache-2.0
StatusBeta (Development Status 4)
Default Port8000 (auto-increments if occupied)
Max Image Size10MB
Supported ImagesPNG, JPG, GIF, WEBP, SVG, BMP, ICO
Max Tabs15 files (workspace mode)

​
Next Steps

Install Now

Get Markdown-OS installed in under a minute

Quick Start Guide

Learn the essentials and start editing

Build docs developers (and LLMs) love

Get started for freeTalk to us