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>
This commit is contained in:
6
web/embed.go
Normal file
6
web/embed.go
Normal file
@@ -0,0 +1,6 @@
|
||||
package web
|
||||
|
||||
import "embed"
|
||||
|
||||
//go:embed templates/*.html static/*
|
||||
var Content embed.FS
|
||||
1
web/static/htmx.min.js
vendored
Normal file
1
web/static/htmx.min.js
vendored
Normal file
File diff suppressed because one or more lines are too long
343
web/static/style.css
Normal file
343
web/static/style.css
Normal file
@@ -0,0 +1,343 @@
|
||||
/* Metacircular Docs — clean technical document styling */
|
||||
|
||||
:root {
|
||||
--bg: #fafafa;
|
||||
--fg: #1a1a1a;
|
||||
--fg-muted: #555;
|
||||
--border: #ddd;
|
||||
--link: #1a56db;
|
||||
--link-hover: #0f3d91;
|
||||
--code-bg: #f0f0f0;
|
||||
--code-border: #ddd;
|
||||
--sidebar-bg: #f5f5f5;
|
||||
--sidebar-active: #e8e8e8;
|
||||
--max-width: 72rem;
|
||||
--content-width: 70ch;
|
||||
--font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
|
||||
--font-mono: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
|
||||
}
|
||||
|
||||
*, *::before, *::after {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
html {
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
font-family: var(--font-body);
|
||||
color: var(--fg);
|
||||
background: var(--bg);
|
||||
line-height: 1.65;
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--link);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:hover {
|
||||
color: var(--link-hover);
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/* Header / Breadcrumbs */
|
||||
|
||||
header {
|
||||
border-bottom: 1px solid var(--border);
|
||||
padding: 0.75rem 1.5rem;
|
||||
background: #fff;
|
||||
}
|
||||
|
||||
.breadcrumb {
|
||||
max-width: var(--max-width);
|
||||
margin: 0 auto;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.breadcrumb .sep {
|
||||
color: var(--fg-muted);
|
||||
margin: 0 0.25rem;
|
||||
}
|
||||
|
||||
/* Main layout */
|
||||
|
||||
main {
|
||||
max-width: var(--max-width);
|
||||
margin: 0 auto;
|
||||
display: flex;
|
||||
gap: 2rem;
|
||||
padding: 1.5rem;
|
||||
min-height: calc(100vh - 8rem);
|
||||
}
|
||||
|
||||
/* Sidebar */
|
||||
|
||||
.sidebar {
|
||||
flex: 0 0 14rem;
|
||||
position: sticky;
|
||||
top: 1.5rem;
|
||||
align-self: flex-start;
|
||||
max-height: calc(100vh - 4rem);
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
.sidebar ul {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.sidebar li {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.sidebar li a {
|
||||
display: block;
|
||||
padding: 0.35rem 0.75rem;
|
||||
border-radius: 4px;
|
||||
font-size: 0.875rem;
|
||||
color: var(--fg);
|
||||
}
|
||||
|
||||
.sidebar li a:hover {
|
||||
background: var(--sidebar-bg);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.sidebar li.active a {
|
||||
background: var(--sidebar-active);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
/* Content */
|
||||
|
||||
#content {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
max-width: var(--content-width);
|
||||
}
|
||||
|
||||
/* Index page */
|
||||
|
||||
.repo-list {
|
||||
display: grid;
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
.repo-card {
|
||||
padding: 1rem 1.25rem;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 6px;
|
||||
background: #fff;
|
||||
}
|
||||
|
||||
.repo-card h2 {
|
||||
margin: 0 0 0.25rem;
|
||||
font-size: 1.15rem;
|
||||
}
|
||||
|
||||
.repo-card p {
|
||||
margin: 0 0 0.5rem;
|
||||
color: var(--fg-muted);
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.doc-count {
|
||||
font-size: 0.8rem;
|
||||
color: var(--fg-muted);
|
||||
}
|
||||
|
||||
/* Repo page */
|
||||
|
||||
.repo-desc {
|
||||
color: var(--fg-muted);
|
||||
margin-bottom: 1.5rem;
|
||||
}
|
||||
|
||||
.doc-list {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.doc-list li {
|
||||
padding: 0.5rem 0;
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
|
||||
.doc-list li:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
|
||||
.toc {
|
||||
margin-bottom: 2rem;
|
||||
padding: 1rem 1.25rem;
|
||||
background: var(--sidebar-bg);
|
||||
border-radius: 6px;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.toc summary {
|
||||
cursor: pointer;
|
||||
font-weight: 600;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.toc ul {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.toc li {
|
||||
padding: 0.15rem 0;
|
||||
}
|
||||
|
||||
.toc-h2 { padding-left: 0; }
|
||||
.toc-h3 { padding-left: 1rem; }
|
||||
.toc-h4 { padding-left: 2rem; }
|
||||
.toc-h5 { padding-left: 3rem; }
|
||||
|
||||
/* Document content */
|
||||
|
||||
.doc-content {
|
||||
line-height: 1.7;
|
||||
}
|
||||
|
||||
.doc-content h1 { font-size: 1.75rem; margin: 2rem 0 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.3rem; }
|
||||
.doc-content h2 { font-size: 1.4rem; margin: 1.75rem 0 0.75rem; border-bottom: 1px solid var(--border); padding-bottom: 0.25rem; }
|
||||
.doc-content h3 { font-size: 1.15rem; margin: 1.5rem 0 0.5rem; }
|
||||
.doc-content h4 { font-size: 1rem; margin: 1.25rem 0 0.5rem; }
|
||||
|
||||
.doc-content h1:first-child { margin-top: 0; }
|
||||
|
||||
.doc-content p {
|
||||
margin: 0.75rem 0;
|
||||
}
|
||||
|
||||
.doc-content code {
|
||||
font-family: var(--font-mono);
|
||||
font-size: 0.875em;
|
||||
background: var(--code-bg);
|
||||
padding: 0.15em 0.35em;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
.doc-content pre {
|
||||
background: var(--code-bg);
|
||||
border: 1px solid var(--code-border);
|
||||
border-radius: 6px;
|
||||
padding: 1rem;
|
||||
overflow-x: auto;
|
||||
line-height: 1.45;
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
|
||||
.doc-content pre code {
|
||||
background: none;
|
||||
padding: 0;
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.doc-content table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 1rem 0;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.doc-content th, .doc-content td {
|
||||
border: 1px solid var(--border);
|
||||
padding: 0.5rem 0.75rem;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.doc-content th {
|
||||
background: var(--sidebar-bg);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.doc-content blockquote {
|
||||
margin: 1rem 0;
|
||||
padding: 0.5rem 1rem;
|
||||
border-left: 3px solid var(--border);
|
||||
color: var(--fg-muted);
|
||||
}
|
||||
|
||||
.doc-content ul, .doc-content ol {
|
||||
padding-left: 1.5rem;
|
||||
}
|
||||
|
||||
.doc-content li {
|
||||
margin: 0.25rem 0;
|
||||
}
|
||||
|
||||
.doc-content img {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
.doc-content hr {
|
||||
border: none;
|
||||
border-top: 1px solid var(--border);
|
||||
margin: 2rem 0;
|
||||
}
|
||||
|
||||
/* Task list (GFM) */
|
||||
.doc-content ul.contains-task-list {
|
||||
list-style: none;
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
/* Error page */
|
||||
|
||||
.error-page {
|
||||
text-align: center;
|
||||
padding: 3rem 0;
|
||||
}
|
||||
|
||||
.error-page h1 {
|
||||
font-size: 3rem;
|
||||
color: var(--fg-muted);
|
||||
}
|
||||
|
||||
/* Loading page */
|
||||
|
||||
.loading {
|
||||
text-align: center;
|
||||
padding: 5rem 0;
|
||||
color: var(--fg-muted);
|
||||
}
|
||||
|
||||
/* Footer */
|
||||
|
||||
footer {
|
||||
border-top: 1px solid var(--border);
|
||||
padding: 0.75rem 1.5rem;
|
||||
text-align: center;
|
||||
font-size: 0.8rem;
|
||||
color: var(--fg-muted);
|
||||
}
|
||||
|
||||
/* Responsive */
|
||||
|
||||
@media (max-width: 768px) {
|
||||
main {
|
||||
flex-direction: column;
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
.sidebar {
|
||||
position: static;
|
||||
flex: none;
|
||||
max-height: none;
|
||||
}
|
||||
|
||||
#content {
|
||||
max-width: 100%;
|
||||
}
|
||||
}
|
||||
17
web/templates/doc.html
Normal file
17
web/templates/doc.html
Normal 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
7
web/templates/error.html
Normal 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
14
web/templates/index.html
Normal 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
42
web/templates/layout.html
Normal 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
20
web/templates/loading.html
Normal 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
11
web/templates/repo.html
Normal 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}}
|
||||
Reference in New Issue
Block a user