godown

godown

A lightweight, standalone Markdown server with embedded dark mode support. Serve your Markdown documentation as beautiful HTML with zero dependencies. Perfect for previewing documentation locally before committing to your repository.

Features

• Zero Dependencies: CSS embedded directly in the binary
• Dark Mode: Automatic theme switching based on system preferences
• Markdown Rendering: Full CommonMark support with tables, fenced code blocks, and auto-heading IDs
• Media Support: Serve images, videos, and other static assets
• Customizable: Optional custom CSS support
• Docker Ready: Multi-arch Docker images (amd64/arm64)
• Lightweight: Single binary, minimal footprint

Quick Start

Standalone Binary

# Download and run
go install github.com/badele/godown@latest

# Serve current directory
godown

# Open http://localhost:8080 in your browser

Docker

# Run with default settings
docker run -v .:/docs -p 8080:8080 badele/godown:latest

Nix

# Run directly with Nix
nix run github:badele/godown

# Or add to your flake.nix

Usage

Command Line Options

Usage of godown:
  -index string
        Default index file (default "README.md")
  -port string
        HTTP server port (default "8080")
  -style string
        Custom CSS file path (optional, uses embedded style by default)

Examples

Using command-line flags:

# Custom port
godown --port 3000

# Custom index file
godown --index index.md

# Custom CSS
godown --style /path/to/custom.css

# All together
godown --port 3000 --index index.md --style custom.css

Using environment variables:

# Custom port
PORT=3000 godown

# Custom index file
INDEX=index.md godown

# Custom CSS
STYLE=/path/to/custom.css godown

# All together
PORT=3000 INDEX=index.md STYLE=custom.css godown

Available environment variables:

• PORT - Server port
• INDEX - Default index file
• STYLE - Custom CSS file path

Priority: Environment variables > Command-line flags > Defaults

# Environment variable takes precedence
PORT=3000 godown --port 8080  # Uses port 3000

Directory Structure

your-docs/
├── README.md           # Index page (/)
├── guide.md            # Accessible at /guide
├── images/
│   └── logo.png        # Accessible at /images/logo.png
└── docs/
    └── api.md          # Accessible at /docs/api

URL Routing

• / → Serves the index file (default: README.md)
• /page → Serves page.md
• /docs/guide → Serves docs/guide.md
• /images/logo.png → Serves static media files directly

Supported Media Files

• Images: .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg, .ico
• Videos: .mp4, .webm, .ogg, .avi, .mov, .mkv
• CSS: .css

Embedded Dark Mode

The embedded CSS includes automatic dark mode that activates based on system preferences:

Light Mode:

• White background
• Dark text
• Blue links

Dark Mode:

• Dark background (#1e1e1e)
• Light text (#e0e0e0)
• Light blue links (#58a6ff)

No configuration needed - it just works!

Custom CSS

If you want to use your own styles:

# Create your custom CSS
cat > custom.css << 'EOF'
body {
    max-width: 1200px;
    font-family: 'Comic Sans MS', cursive;
    background: linear-gradient(to right, #667eea 0%, #764ba2 100%);
}
EOF

# Use it
godown --style custom.css

If the custom CSS file is not found, godown automatically falls back to the embedded CSS.

For Developers

Want to contribute or build from source? See DEVELOPMENT.md for:

• Building from source
• Development environment setup
• Pre-commit hooks
• Testing
• CI/CD pipeline
• Release process
• Commit message conventions

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! See DEVELOPMENT.md for detailed guidelines.

Credits

Built with:

• gomarkdown/markdown - Markdown parser
• release-please - Automated releases
• pre-commit - Git hooks framework

Changelog

See CHANGELOG.md (auto-generated by release-please)