md-http-server
Advanced tools
A simple HTTP server for rendering markdown files with Mermaid diagrams, Table of Contents, and Live Reload
A simple, fast HTTP server for rendering Markdown files with beautiful default styling.
.md files as beautifully formatted HTMLNo installation required! Just run:
npx md-http-server
npm install -g md-http-server
npm install md-http-server
Serve the current directory on port 3000:
npx md-http-server
npx md-http-server ./docs
npx md-http-server -p 8080
Enable automatic page refresh when markdown files change:
npx md-http-server --watch
npx md-http-server -v
Protect your content with Google OAuth authentication:
npx md-http-server --auth
See Authentication section for full setup instructions.
npx md-http-server [directory] -p [port] -v -w --watch-debounce [ms] --auth --auth-config [path] --config [path]
Arguments:
directory - Directory to serve (default: current directory)Options:
-c, --config <path> - Path to config file (JSON or YAML)-p, --port <port> - Port to listen on (default: 3000)-v, --verbose - Enable verbose logging-w, --watch - Enable live reload when markdown files change--watch-debounce <ms> - Debounce delay for file changes in milliseconds (default: 500)--auth - Enable Google OAuth authentication--auth-config <path> - Path to auth config file (default: .md-server-auth.json)-V, --version - Output version number-h, --help - Display helpSubcommands:
init - Create a configuration file interactivelyvalidate --config <path> - Validate a configuration fileInstead of passing options via command line, you can store all settings in a configuration file.
Interactive creation:
npx md-http-server init
Answer the prompts to create md-server.config.json.
Manual creation:
Create md-server.config.json (JSON format):
{
"directory": "./docs",
"port": 8080,
"verbose": false,
"watch": true,
"watchDebounce": 500
}
Or md-server.config.yaml (YAML format):
directory: ./docs
port: 8080
verbose: false
watch: true
watchDebounce: 500
npx md-http-server --config ./md-server.config.json
Use ${VAR_NAME} syntax for sensitive values:
{
"authProvider": "GOOGLE",
"authConfig": {
"clientId": "${GOOGLE_CLIENT_ID}",
"clientSecret": "${GOOGLE_CLIENT_SECRET}",
"sessionSecret": "${SESSION_SECRET:-dev-secret-change-me}"
}
}
The :- syntax provides a default value if the environment variable is not set.
Full example with authentication:
directory: ./docs
port: 8080
watch: true
authProvider: GOOGLE
authConfig:
clientId: ${GOOGLE_CLIENT_ID}
clientSecret: ${GOOGLE_CLIENT_SECRET}
sessionSecret: ${SESSION_SECRET}
allowedDomains:
- yourcompany.com
Settings are applied in this order (highest priority last):
Example:
# Config file sets port to 8080, but CLI overrides to 3000
npx md-http-server --config config.json --port 3000
Ensure your configuration file is valid:
npx md-http-server validate --config ./md-server.config.json
This checks:
| Option | Type | Default | Description |
|---|---|---|---|
directory | string | . | Directory to serve |
port | number | 3000 | Server port (1-65535) |
verbose | boolean | false | Enable verbose logging |
watch | boolean | false | Enable live reload |
watchDebounce | number | 500 | Debounce delay in ms |
authProvider | string/null | null | OAuth provider ("GOOGLE" or null) |
authConfig.clientId | string | - | OAuth Client ID (required if authProvider set) |
authConfig.clientSecret | string | - | OAuth Client Secret (required if authProvider set) |
authConfig.sessionSecret | string | - | Session encryption secret |
authConfig.callbackUrl | string | - | OAuth callback URL (auto-detected) |
authConfig.allowedDomains | string[] | [] | Restrict login to email domains |
Serve your project documentation:
cd my-project
npx md-http-server ./docs -p 8080
Then open http://localhost:8080 in your browser.
Preview your README before committing:
npx md-http-server
# Open http://localhost:3000/README.md
Browse and view your markdown notes:
npx md-http-server ~/Documents/notes
Edit markdown files and see changes instantly:
npx md-http-server ./docs --watch --verbose
# Open http://localhost:3000/your-file.md
# Edit the file in your editor, save, and watch the browser auto-reload!
You can also use md-http-server as a library in your Node.js applications:
import { createServer } from 'md-http-server';
const server = createServer({
port: 3000,
directory: './content',
verbose: true,
watch: true,
watchDebounce: 500
});
await server.start();
import { createServer, loadAuthConfig } from 'md-http-server';
// Load auth config from file
const authResult = loadAuthConfig('./.md-server-auth.json');
if (!authResult.success) {
console.error('Auth config error:', authResult.error);
process.exit(1);
}
const server = createServer({
port: 3000,
directory: './content',
authConfig: authResult.config
});
await server.start();
All .md files are automatically rendered as HTML with:
Create beautiful diagrams directly in your markdown files using Mermaid syntax:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[OK]
B -->|No| D[End]
```
Supported diagram types:
All diagrams are rendered client-side using Mermaid.js.
The live reload feature automatically refreshes your browser when markdown files change, making it perfect for writing and previewing documentation.
How it works:
--watch flagFeatures:
Example:
# Start server with live reload
npx md-http-server --watch
# Custom debounce delay (wait 1 second after file changes)
npx md-http-server --watch --watch-debounce 1000
Automatically generates a Table of Contents for your markdown files with:
You can also insert a TOC manually anywhere in your document using [TOC] or [[toc]].
When accessing a directory, you'll see:
Enable Google OAuth authentication to protect your markdown content.
Create a Google Cloud Project
Create OAuth Credentials
http://localhost:3000/__auth/callbackCreate Config File
Create .md-server-auth.json in your project root:
{
"clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
"clientSecret": "YOUR_CLIENT_SECRET",
"allowedDomains": ["example.com"]
}
Config Options:
clientId (required) - Google OAuth Client IDclientSecret (required) - Google OAuth Client SecretcallbackUrl (optional) - Override auto-detected callback URLallowedDomains (optional) - Restrict login to specific email domainssessionSecret (optional) - Session encryption secret (auto-generated if not provided)sessionMaxAge (optional) - Session duration in milliseconds (default: 24 hours)Start Server with Auth
npx md-http-server --auth
Restrict access to users from specific email domains:
{
"clientId": "...",
"clientSecret": "...",
"allowedDomains": ["company.com", "partner.org"]
}
Only users with @company.com or @partner.org email addresses can access the content.
When authentication is enabled, these routes are available:
/__auth/login - Initiates Google OAuth flow/__auth/callback - OAuth callback (internal use)/__auth/error - Displays authentication errors/__logout - Logs out current user.md-server-auth.json - Add it to your .gitignore:
.md-server-auth.json
The server includes built-in protections against:
git clone <repository-url>
cd md-server
npm install
npm run build
npm run dev
npm test
MIT
Contributions are welcome! Please feel free to submit a Pull Request.
FAQs
A simple HTTP server for rendering markdown files with Mermaid diagrams, Table of Contents, and Live Reload
The npm package md-http-server receives a total of 4 weekly downloads. As such, md-http-server popularity was classified as not popular.
We found that md-http-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.