Quick Start for End Users

Get your documentation site running in under 5 minutes!

I Want To...

🏃‍♂️ Quickly Test Locally (30 seconds)

Perfect for: Trying out servemd with your existing docs.

# Option 1: Using uvx (recommended - no installation needed)
cd /path/to/your/docs
uvx --from servemd docs-server

# Option 2: Using Docker
docker run -it --rm -p 8080:8080 -v $(pwd):/app/docs ghcr.io/yourusername/servemd:latest

Visit: http://localhost:8080

Requirements: Your docs directory needs: - index.md (homepage) - sidebar.md (navigation) - topbar.md (top bar)

📦 Deploy My Docs as a Docker Image (5 minutes)

Perfect for: Production deployment, CI/CD, Kubernetes.

Step 1: Create Dockerfile in your docs directory:

FROM ghcr.io/yourusername/servemd:latest
COPY . /app/docs/
ENV BASE_URL=https://docs.yourcompany.com

Step 2: Build and run:

# Build
docker build -t my-company-docs:latest .

# Run
docker run -p 8080:8080 my-company-docs:latest

# Push to registry
docker tag my-company-docs:latest ghcr.io/mycompany/docs:latest
docker push ghcr.io/mycompany/docs:latest

Full guide →

🖥️ Use Locally for Development (2 minutes)

Perfect for: Writing documentation with live preview.

Create serve-docs.sh:

#!/bin/bash
DOCS_ROOT="${1:-.}" PORT="${PORT:-8080}" DEBUG=true uvx --from servemd docs-server

Usage:

chmod +x serve-docs.sh
./serve-docs.sh

# Custom directory
./serve-docs.sh ./my-docs

# Custom port
PORT=3000 ./serve-docs.sh

Full guide →

☁️ Deploy to Cloud Platform (5-10 minutes)

Perfect for: Hosting publicly accessible documentation.

Heroku

heroku create my-docs
heroku container:push web
heroku container:release web

Railway

railway init
railway up

Fly.io

flyctl launch
flyctl deploy

Full guide →

⚙️ Deploy to Kubernetes/k3s (10 minutes)

Perfect for: Self-hosted, enterprise deployments.

# Quick k3s deployment
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docs-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: docs-server
  template:
    metadata:
      labels:
        app: docs-server
    spec:
      containers:
      - name: docs-server
        image: ghcr.io/mycompany/docs:latest
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: docs-server
spec:
  selector:
    app: docs-server
  ports:
  - port: 80
    targetPort: 8080
EOF

Full guide →

Common Patterns

Pattern 1: Development → Production Workflow

# 1. Develop locally with live reload
DEBUG=true uvx --from servemd docs-server

# 2. Build Docker image
docker build -t my-docs:latest .

# 3. Test production build locally
docker run -p 8080:8080 my-docs:latest

# 4. Push to registry
docker push ghcr.io/mycompany/docs:latest

# 5. Deploy to production
kubectl set image deployment/docs-server docs-server=ghcr.io/mycompany/docs:latest

Pattern 2: Git-based Deployment

# Create docs repository
git init
git add .
git commit -m "Initial docs"
git push

# Deploy automatically via GitHub Actions
# (See CI/CD examples in deployment guides)

Pattern 3: Multi-environment Setup

# Development
DOCS_ROOT=./docs DEBUG=true uvx --from servemd docs-server

# Staging
docker run -p 8080:8080 -e BASE_URL=https://staging-docs.com my-docs:staging

# Production
docker run -p 8080:8080 -e BASE_URL=https://docs.com my-docs:latest

Directory Structure

Your documentation directory should look like this:

my-documentation/
├── index.md          # Required: Homepage
├── sidebar.md        # Required: Navigation menu
├── topbar.md         # Required: Top bar links
├── llms.txt          # Optional: AI assistant index
├── assets/           # Optional: Images, logos, etc.
│   └── logo.png
├── guides/           # Your content
│   ├── getting-started.md
│   └── advanced.md
├── api/              # API documentation
│   └── reference.md
└── Dockerfile        # For containerized deployment

Minimal Example Files

index.md: 

# Welcome to Our Documentation

Get started with our product in minutes!

- [Quick Start](guides/getting-started.html)
- [API Reference](api/reference.html)

sidebar.md: 

# Navigation

## Getting Started
- [Introduction](index.html)
- [Installation](guides/getting-started.html)

## API
- [Reference](api/reference.html)

topbar.md: 

# My Documentation

[GitHub](https://github.com/mycompany/product) • [Support](https://support.mycompany.com)

Configuration

Configure via environment variables:

Variable Default Description
DOCS_ROOT ./docs Path to documentation directory
PORT 8080 Server port
DEBUG false Enable debug mode (auto-reload)
BASE_URL Auto-detected Base URL for absolute links
CACHE_ROOT ./__cache__ Cache directory path

Examples:

# Local development
DOCS_ROOT=./my-docs PORT=3000 DEBUG=true uvx --from servemd docs-server

# Docker
docker run -p 8080:8080 \
  -e BASE_URL=https://docs.mycompany.com \
  -e DEBUG=false \
  my-docs:latest

Full configuration guide →

Troubleshooting

Required Files Missing

Error: index.md, sidebar.md, or topbar.md not found

Solution: Create the three required files in your DOCS_ROOT: 

touch index.md sidebar.md topbar.md

Port Already in Use

Error: Address already in use

Solution: Use a different port: 

PORT=3000 uvx --from servemd docs-server

Docker Volume Issues

Error: Permission denied

Solution: Check volume mount paths: 

# Correct
docker run -v $(pwd):/app/docs ...

# Also works
docker run -v /absolute/path/to/docs:/app/docs ...

Next Steps

Choose your deployment method:

  1. Local Development Guide - uvx, pipx, Docker volumes
  2. Docker Image Guide - Build custom images
  3. Cloud Platforms - Heroku, Railway, Fly.io, etc.
  4. Kubernetes - k8s, k3s, Helm charts

Getting Help