Live Watch Server (mdslide watch)

The watch command launches a local development server with a built-in live preview client. Whenever you save changes to your Markdown source file, the compiler automatically rebuilds the slides and reloads your browser instantly.

---

Usage

mdslide watch <input-file> [options]

Examples

# Start watch server (hosts on http://localhost:3500)
mdslide watch slides.md

# Start server on port 4000 and open the browser automatically
mdslide watch slides.md --port 4000 --open

# Override default theme settings during preview
mdslide watch slides.md --theme Notion

# Compile once to confirm the deck is valid, without starting the server
mdslide watch slides.md --dry-run

# Machine-readable startup + recompile events
mdslide watch slides.md --json

---

Options & Flags Reference

Below is the list of flags available for the watch command:

Flag	Short	Type	Default Value	Description
--theme <theme>	-t	string	Config default	Override theme style during preview: light, dark, notion, terminal, gradient, corporate, or solarized.
--port <port>	-p	number	3500	Port for the live-reload development server.
--open	-	boolean	false	Automatically launch the web browser and open the preview page on startup.
--verbose	-	boolean	false	Outputs detailed compiler and web socket logs in the console.
--silent	-	boolean	false	Suppresses all logging output.

This command also accepts the global flags (--json, --no-input, --yes, --dry-run, --timeout); --json and --dry-run have watch-specific behavior described below.

:::note Stdin is not supported watch always needs a real file on disk to keep watching for changes, so passing - as <input-file> is rejected with ERR_STDIN_UNSUPPORTED. Save the deck to a file and pass its path instead. :::

---

Dry Run Mode (--dry-run)

Passing --dry-run compiles the deck once to prove it is valid and prints the result, but never starts the HTTP/live-reload server. This is useful in CI or agent workflows that just want to confirm a deck watches cleanly without holding a process open.

Machine-Readable Output (--json)

With --json, the server startup line is a single JSON object on stdout:

{ "success": true, "url": "http://localhost:3500", "port": 3500, "watching": "/abs/path/slides.md" }

After that, every recompile triggered by a save prints one compact JSON line to stdout (the whole stream is NDJSON) so a supervising process can tell what each edit did without polling:

{"event":"recompile","success":true,"slides":5,"warnings":[]}
{"event":"recompile","success":false,"error":"Unclosed code fence.","code":"ERR_COMPILE"}

With --dry-run --json, the one-shot compile result is printed instead of the startup line: { "file", "success": true, "dryRun": true, "slides": <count> }, and the process exits without starting the server.

---

How It Works

1. File Watcher: mdslide uses a file watcher on the input Markdown file.
2. Local Server: Starts a lightweight HTTP server on the designated port (default 3500).
3. Websocket Sync: Inserts a small live-reload script into the temporary HTML slide deck. This script maintains a WebSocket connection to the CLI watcher.
4. Instant Reload: Saving your Markdown file compiles the deck, saves the temporary build, and signals the active browser tab via WebSocket to refresh the slides immediately.