mc/mcdoc

Files

Kyle Isom 28afaa2c56 Implement mcdoc v0.1.0: public documentation server

Single-binary Go server that fetches markdown from Gitea (mc org),
renders to HTML with goldmark (GFM, chroma syntax highlighting,
heading anchors), and serves a navigable read-only documentation site.

Features:
- Boot fetch with retry, webhook refresh, 15-minute poll fallback
- In-memory cache with atomic per-repo swap
- chi router with htmx partial responses for SPA-like navigation
- HMAC-SHA256 webhook validation
- Responsive CSS, TOC generation, priority doc ordering
- $PORT env var support for MCP agent port assignment

33 tests across config, cache, render, and server packages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-27 13:04:15 -07:00

2.4 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mcdoc is a public documentation server for the Metacircular platform. It fetches markdown files from Gitea repositories, renders them to HTML, and serves a navigable read-only site. No authentication required.

See ARCHITECTURE.md for the full specification.

Priorities (in order): correctness, simplicity, readability.

Build Commands

make all          # vet → lint → test → build
make mcdoc        # build binary with version injection
make build        # compile all packages
make test         # run all tests
make vet          # go vet
make lint         # golangci-lint
make devserver    # build and run locally with srv/mcdoc.toml
make clean        # remove built binaries
make docker       # build container image

Run a single test:

go test ./internal/server -run TestDocPage

Tech Stack

Language: Go 1.25+, CGO_ENABLED=0, statically linked
Module path: git.wntrmute.dev/mc/mcdoc
Config: TOML via go-toml/v2, env overrides via MCDOC_*
HTTP: chi router, htmx for navigation
Rendering: goldmark (GFM), chroma (syntax highlighting)
Templates: Go html/template, embedded via //go:embed
Linting: golangci-lint v2

Architecture

Single binary, single container
Fetches markdown from Gitea API (mc org, public repos)
Renders to HTML at fetch time, caches in memory
Refreshes via Gitea push webhooks + 15-minute poll fallback
mc-proxy terminates TLS, mcdoc serves plain HTTP
No database, no local state beyond config

Package Structure

cmd/mcdoc/ — CLI entry point (cobra: server subcommand)
internal/config/ — TOML config loading
internal/gitea/ — Gitea API client
internal/cache/ — In-memory content cache
internal/render/ — goldmark rendering pipeline
internal/server/ — HTTP server, chi routes, htmx handlers
web/ — Templates and static files, embedded via //go:embed

Critical Rules

No authentication — this is a public site
Never serve stale-on-error without logging the staleness
Webhook secret must be validated (HMAC-SHA256) before processing
All user-supplied path segments must be sanitized (no path traversal)
Template rendering must use html/template (auto-escaping), never text/template
No CGo in production
Generated code is never edited by hand

2.4 KiB Raw Permalink Blame History