mdserve

Markdown HTTPS preview in one command. GitHub-faithful rendering, live reload, and an HTTPS URL like https://mdserve-7f3a.local via portless.

npx github:xemoe/mdserve ./README.md

  mdserve v1.2.0

  ➜  Serving   README.md
  ➜  HTTPS     https://mdserve-7f3a.local
  ➜  Local     http://127.0.0.1:52310

  watching for changes — press Ctrl-C to stop

• GitHub-rich markdown — tables, task lists, footnotes, > [!NOTE] alerts, heading anchors with GitHub slugs, raw HTML (<details>, badges)
• Syntax highlighting — shiki with the Monokai theme; code blocks stay dark in both page themes
• Mermaid — ```mermaid fences render as diagrams (lazy-loaded from CDN)
• Live reload — save the file, the browser refreshes
• Directory mode — npx github:xemoe/mdserve ./docs serves an index of every .md in the tree
• Dark/light theme — follows the OS, with a manual auto/light/dark toggle
• HTTPS via portless — auto-registers a unique https://mdserve-<id>.local per run (concurrent previews never collide); pass --name for a stable URL. Falls back to plain HTTP when portless isn't installed. Loopback only, never on the LAN.

npx github:xemoe/mdserve                      # serve the current directory
npx github:xemoe/mdserve README.md            # serve one file at /
npx github:xemoe/mdserve ./docs --name docs   # stable URL: https://docs.local
npx github:xemoe/mdserve --port 5123          # fixed port
npx github:xemoe/mdserve --no-portless        # plain http://127.0.0.1:<port> only

• Node.js ≥ 20 (macOS; on Linux, live reload in subdirectories needs Node ≥ 22.4)
• portless installed and its proxy running, for the HTTPS URL (optional — without it mdserve serves plain HTTP). Run portless trust once to avoid certificate warnings.

npm install
npm test        # node:test with coverage