mc/mcdoc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement mcdoc v0.1.0: public documentation server

Browse Source 
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>
This commit is contained in:
Kyle Isom
2026-03-27 13:04:15 -07:00
parent 0578dbcb02
commit 28afaa2c56
31 changed files with 2870 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
web/templates/doc.html Normal file
View File

@@ -0,0 +1,17 @@
{{define "content"}}
{{if .TOC}}
<nav class="toc">
<details open>
<summary>Contents</summary>
<ul>
{{range .TOC}}
<li class="toc-h{{.Level}}"><a href="#{{.ID}}">{{.Text}}</a></li>
{{end}}
</ul>
</details>
</nav>
{{end}}
<article class="doc-content">
{{.Content}}
</article>
{{end}}

7
web/templates/error.html Normal file
View File

@@ -0,0 +1,7 @@
{{define "content"}}
<div class="error-page">
<h1>{{.Code}}</h1>
<p>{{.Message}}</p>
<a href="/" hx-get="/" hx-target="#content" hx-push-url="true">Back to index</a>
</div>
{{end}}

14
web/templates/index.html Normal file
View File

@@ -0,0 +1,14 @@
{{define "content"}}
<h1>Metacircular Platform Documentation</h1>
<div class="repo-list">
{{range .Repos}}
<div class="repo-card">
<h2><a href="/{{.Name}}/" hx-get="/{{.Name}}/" hx-target="#content" hx-push-url="true">{{.Name}}</a></h2>
{{if .Description}}<p>{{.Description}}</p>{{end}}
<span class="doc-count">{{len .Docs}} document{{if ne (len .Docs) 1}}s{{end}}</span>
</div>
{{else}}
<p>No repositories found.</p>
{{end}}
</div>
{{end}}

42
web/templates/layout.html Normal file
View File

@@ -0,0 +1,42 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{if .Title}}{{.Title}} — {{end}}Metacircular Docs</title>
<link rel="stylesheet" href="/static/style.css">
<script src="/static/htmx.min.js"></script>
</head>
<body>
<header>
<nav class="breadcrumb">
<a href="/" hx-get="/" hx-target="#content" hx-push-url="true">Metacircular Docs</a>
{{range .Breadcrumbs}}
<span class="sep">/</span>
<a href="{{.URL}}" hx-get="{{.URL}}" hx-target="#content" hx-push-url="true">{{.Label}}</a>
{{end}}
</nav>
</header>
<main>
{{if .Sidebar}}
<aside class="sidebar">
<nav>
<ul>
{{range .Sidebar}}
<li{{if .Active}} class="active"{{end}}>
<a href="{{.URL}}" hx-get="{{.URL}}" hx-target="#content" hx-push-url="true">{{.Label}}</a>
</li>
{{end}}
</ul>
</nav>
</aside>
{{end}}
<div id="content">
{{block "content" .}}{{end}}
</div>
</main>
<footer>
{{if .LastUpdated}}<time>Last updated: {{.LastUpdated}}</time>{{end}}
</footer>
</body>
</html>

20
web/templates/loading.html Normal file
View File

@@ -0,0 +1,20 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Loading — Metacircular Docs</title>
<link rel="stylesheet" href="/static/style.css">
<meta http-equiv="refresh" content="5">
</head>
<body>
<main>
<div id="content">
<div class="loading">
<h1>Metacircular Docs</h1>
<p>Fetching documentation from Gitea... please wait.</p>
</div>
</div>
</main>
</body>
</html>

11
web/templates/repo.html Normal file
View File

@@ -0,0 +1,11 @@
{{define "content"}}
<h1>{{.RepoName}}</h1>
{{if .RepoDescription}}<p class="repo-desc">{{.RepoDescription}}</p>{{end}}
<ul class="doc-list">
{{range .Docs}}
<li>
<a href="/{{$.RepoName}}/{{.URLPath}}" hx-get="/{{$.RepoName}}/{{.URLPath}}" hx-target="#content" hx-push-url="true">{{.Title}}</a>
</li>
{{end}}
</ul>
{{end}}