doc

A lightweight, read-only documentation aggregation service. It discovers markdown documents across your GitHub organization, syncs them automatically, and serves them through a simple filesystem-like HTTP API.

Why this exists

Documentation lives scattered across repositories. Rather than manually curating a docs site, this service treats your org's repos as the source of truth. It discovers README.md and files under docs/ automatically, parses YAML frontmatter, and exposes everything through a stable URL structure. The API is designed around a filesystem metaphor because developers already think in paths.

API

The API is organized as a virtual filesystem rooted at each repository:

GET /                          → list all public repos
GET /{repo}/                   → list documents in a repo
GET /{repo}/__tree__           → recursive tree of all documents
GET /{repo}/{path}             → fetch a specific document
GET /__index__                 → global search index across all repos
GET /sitemap.xml               → SEO sitemap for crawlers
GET /health                    → health check

OpenAPI / Swagger

The full API schema is available at runtime:

• GET /openapi.json — OpenAPI 3.1 JSON
• GET /openapi.yaml — OpenAPI 3.1 YAML
• GET /swagger-ui/ — Interactive Swagger UI

Raw markdown

Append ?raw=1 or send Accept: text/markdown to get the raw markdown body without JSON wrapping.

Example

# List all repositories
curl https://doc.example.com/

# Get a document as JSON (frontmatter + body)
curl https://doc.example.com/backrooms/getting-started

# Get raw markdown
curl https://doc.example.com/backrooms/getting-started?raw=1

Document discovery

Documents are discovered via a GitHub App with read access to your organization's repositories. On each sync cycle:

1. Lists all public repositories
2. Extracts README.md (mapped to / within the repo)
3. Extracts all files under docs/ (mapped without the docs/ prefix)
4. Parses YAML frontmatter into structured metadata
5. Soft-deletes documents that no longer exist upstream

Private repositories are never indexed or exposed.

Frontmatter

Documents may include YAML frontmatter:

---
title: Getting Started
description: How to enter the Backrooms
author: sienna
tags: [guide, safety]
---

# Getting Started

All frontmatter fields are optional. The title field is used for display; description and tags power search and indexing.

Running

With Docker

docker run -p 8080:8080 \
  -e DOCS__GITHUB_APP_ID=4017767 \
  -e DOCS__GITHUB_PRIVATE_KEY="$(cat key.pem)" \
  -e DOCS__DATABASE_URL="postgres://user:pass@host/db" \
  ghcr.io/sunbeamdotpt/doc:latest

Configuration

Environment Variable	Description
DOCS__GITHUB_APP_ID	GitHub App ID
DOCS__GITHUB_PRIVATE_KEY	GitHub App private key (PEM)
DOCS__DATABASE_URL	PostgreSQL connection string
DOCS__BIND_ADDRESS	HTTP bind address (default: 0.0.0.0:8080)
DOCS__BASE_URL	External base URL for sitemap/links
DOCS__POLL_INTERVAL_SECONDS	Sync interval (default: 300)

Helm

The chart is published as an OCI artifact to GitHub Container Registry:

# Install directly from GHCR
helm install doc oci://ghcr.io/sunbeamdotpt/doc/chart --version 0.1.0

# Or pull it locally first
helm pull oci://ghcr.io/sunbeamdotpt/doc/chart --version 0.1.0 --untar
helm install doc ./doc

You can also use the local source at helm/doc/:

helm install doc ./helm/doc

See values.yaml for configuration options including Kubernetes secrets support.

Architecture at a glance

• Rust + Axum — async HTTP API
• PostgreSQL + sqlx — strongly-typed queries with compile-time checking
• moka LRU cache — hot paths cached with TTL invalidation
• Background sync — tokio task polls GitHub on a configurable interval
• Multi-arch container — ~15-20MB distroless image for linux/amd64 and linux/arm64

License

MIT — Copyright (c) 2026 Sunbeam Studios