MD Hub Secure

MD Hub Secure is a Go-first documentation platform for serving Markdown as secure, fast HTML with room for later sync, collaboration, and offline features.

Current Status

This repository now contains the Milestone 1 foundation scaffold:

• Go application server with chi routing, slog logging, config loading, and graceful shutdown
• SQLite/libsql-oriented data layer with startup migrations
• Markdown rendering pipeline with wiki-link rewriting, tag extraction, and SSR templates
• Content-addressed attachment storage with secure serving
• Preact + Vite frontend scaffold for later hydration-focused UI work
• Docker, Compose, CI, OpenAPI, and local development targets

Quick Start

Prerequisites

• Go 1.24+
• Node.js 24+
• npm 11+
• Docker (optional)
• CGO-capable toolchain for go-libsql
• air for Go live reload (go install github.com/air-verse/air@latest)

Development Mode (with live reload)

Run both the Go server and Vite dev server with live reload:

make dev

This starts:

• Go server with air live reload on http://localhost:8080
• Vite dev server with HMR on http://localhost:5173
• The Go server proxies /app/* requests to Vite, so access the app at http://localhost:8080/app/

You can also run them separately in two terminals:

# Terminal 1 - Go server with live reload
make dev-server

# Terminal 2 - Vite dev server  
make dev-web

Production Mode

Build the web app and run the Go server without Vite proxy:

make web-install
make web-build
make server-run

The server listens on http://localhost:8080 by default.

Common commands

make server-test
make server-build
make docker-build
make ci
make fmt

Configuration

Configuration can come from:

1. config.json via MD_HUB_CONFIG
2. Environment variables

Supported variables:

• MD_HUB_SERVER_ADDR
• MD_HUB_DATABASE_PATH
• MD_HUB_DATABASE_PRIMARY_URL
• MD_HUB_DATABASE_AUTH_TOKEN
• MD_HUB_CONTENT_SOURCE_DIR
• MD_HUB_CONTENT_STORE_DIR
• MD_HUB_WEB_DIST_DIR
• MD_HUB_DEV_VITE_URL - Set to proxy /app/* to Vite dev server (e.g. http://localhost:5173)
• MD_HUB_LOG_LEVEL

Noted Gaps

• The docs describe both a single-binary system and a separate Vite/Preact app. This implementation keeps the Go server as the primary runtime and treats the web app as compiled static assets.
• The docs call for golang-migrate, but the current foundation uses an internal migration runner while go-libsql integration details are validated.
• The sync docs describe JSON messages while the Milestone 1 layout mentions a protobuf package; both are preserved in packages/protocol/ pending a later protocol lock.