mdwatch (Markdown Watcher CLI)

A simple command-line tool to preview Markdown files in a web browser. It serves the rendered HTML version of a Markdown file over HTTP, allowing you to easily preview your Markdown content locally.

Features

• Serve a Markdown file as HTML via a local web server
• Automatically open the preview in your default web browser
• Auto reload on save
• Supports specifying the file path, server IP, and port via command-line arguments
• Warns when binding to 0.0.0.0 to expose the server to the network
• Sanitizes rendered HTML to prevent injection of unsafe content

Installation

You have three options: via Cargo, via prebuilt script, or manual install.

1. Easiest: Install via Cargo (Recommended)

If you have Rust installed, you can install directly from crates.io:

cargo install mdwatch

This is the most "Rusty" and portable way.
It automatically downloads, compiles, and installs the latest version to your $HOME/.cargo/bin.

If you want even faster installs with prebuilt binaries, check out cargo-binstall:

cargo binstall mdwatch

2. Quick Install via Script

Alternative: Installs the latest release binary to your system PATH.

curl -sSfL https://raw.githubusercontent.com/santoshxshrestha/mdwatch/main/scripts/install.sh | bash

• This script will:
  1. Build mdwatch in release mode (if Rust is present).
  2. Copy the binary to /usr/local/bin.
  3. Make it executable.

Tip: You may need to enter your password for sudo privileges.

3. Manual Build & Install

If you prefer full control or want to customize the build:

1. Clone the repository:

   git clone https://github.com/santoshxshrestha/mdwatch.git
   cd mdwatch
   

2. Build the Release Binary:

   cargo build --release
   

   This places the binary at target/release/mdwatch.

3. Copy to a PATH directory (e.g., /usr/local/bin):

   sudo cp target/release/mdwatch /usr/local/bin/mdwatch
   

4. (Optional) Ensure executable permission:

   sudo chmod +x /usr/local/bin/mdwatch
   

5. Run from anywhere:

   mdwatch
   

Using with Nix (Flakes)

If you have Nix (version 2.4 or later) with flakes enabled, you can use nix run to run mdwatch without installing Rust or any dependencies globally. You can also use nix develop to get a full development environment for hacking on the project.

Run mdwatch instantly (no install needed)

From the current directory

nix run

This will build and run the latest version of mdwatch from the flake in the current directory. You can pass arguments as usual:

nix run . -- README.md [--ip 127.0.0.1] [--port 3000]

Directly from GitHub (no clone required)

You can also run the latest version of mdwatch directly from GitHub, without cloning the repository:

nix run github:santoshxshrestha/mdwatch -- README.md [--ip 127.0.0.1] [--port 3000]

This will fetch, build, and run mdwatch from the official repository. You can pass any arguments after the -- as usual.

Enter a development environment

If you want to contribute or develop, enter a shell with all dependencies (Rust, cargo, etc) using:

nix develop

This gives you a reproducible environment with everything needed to build, test, and run mdwatch.

Note:

• You need Nix 2.4+ with flakes enabled. See the Nix Flakes documentation for setup help.
• On NixOS, flakes are usually enabled by default. On other systems, you may need to add experimental-features = nix-command flakes to your ~/.config/nix/nix.conf.

Uninstallation

You can uninstall using the provided script or manually:

1. Quick Uninstall via Script

curl -sSfL https://raw.githubusercontent.com/santoshxshrestha/mdwatch/main/scripts/uninstall.sh | bash

2. Manual Uninstall

Remove the binary from your PATH:

sudo rm /usr/local/bin/mdwatch

or

sudo rm /usr/bin/mdwatch

If you also want to remove your cloned repository:

rm -rf ~/mdwatch

If installed with Cargo:

cargo uninstall mdwatch

Usage

Run the tool with the required and optional arguments:

mdwatch README.md [--ip 127.0.0.1] [--port 3000]

• file: Path to the Markdown file to preview (required)

• --ip: IP address to bind the server to (default: 127.0.0.1)

• --port: Port number for the server (default: 3000)

[!NOTE] If you bind to 0.0.0.0, the tool will warn you because this exposes the server to you local network. When binding to 0.0.0.0, the preview URL opened in your browser will use localhost as the hostname.

Example

mdwatch  notes.md --ip 0.0.0.0 --port 8080

This will serve the Markdown file accessible on all network interfaces and open the preview at http://localhost:8080 in your browser.

Security

• The rendered HTML is sanitized to prevent injection of unsafe content.
• Use caution when binding to 0.0.0.0 or any public-facing IP.
• This tool is intended for local development and preview purpose only.

License

The project is made available under the MIT license. See the LICENSE file for more information.