# Shelf

> Static Documentation Hosting

> Generated: 2026-07-19 · Source commit: ecc96a9 · Product: Shelf · Canonical: https://docs.cocoar.dev/shelf/ · Version: v2.2

Shelf your Docs. Multi-product, multi-version documentation hosting for Cocoar.

## Table of Contents

### Introduction

- [Getting Started](/guide/getting-started.md): What Shelf is and the five-minute path from a VitePress build to hosted, versioned documentation: run the container, register a product, upload a ZIP.
- [How It Works](/guide/how-it-works.md): Architecture in one page — an ASP.NET Core server over a docs volume: version auto-detection, latest-redirects, base path rewriting, and PostgreSQL for products, users and analytics.

### Setup

- [Docker](/guide/docker.md): Run Shelf as a Docker container: image tags, the docs/config volume mounts, a compose example and reverse-proxy notes.
- [Configuration](/guide/configuration.md): Every configuration option — PostgreSQL connection, volumes, Modgud federation, API keys, access log, upload limits — via configuration.json or Shelf__ environment variables.
- [Authentication](/guide/authentication.md): Shelf's two auth surfaces: human admin login federated to Modgud (OIDC code flow with SSO, no local passwords) and Bearer API keys for CI/CD uploads.

### Deployment

- [Product Registration](/guide/product-registration.md): Register products via Admin UI, API or JSON seed files: display metadata, tags, visibility, per-product API keys, and how the one-time JSON import into the database works.
- [Upload API](/guide/upload-api.md): Deploy documentation from CI/CD: the ZIP upload endpoint, API-key authentication, version format rules, and ready-to-use GitHub Actions examples.
- [Admin UI](/guide/admin-ui.md): The built-in web interface at /admin — manage products and versions, browse analytics and the access log, configure API keys and GeoIP. Desktop-only by design.

### Details

- [URL Routing](/guide/url-routing.md): How URLs map to products and versions: routing rules, latest-version redirects, SemVer detection, and what non-doc paths fall through to.
- [Base Path Rewriting](/guide/base-path-rewriting.md): Why VitePress sites built with base '/' work under /product/version/ URLs: the HTML/CSS/JS response rewriter and its placeholder mechanics.
- [Caching](/guide/caching.md): The cache headers Shelf applies: immutable hashed assets, revalidated HTML, and how the file watcher invalidates version manifests.
- [LLM Documentation](/guide/llm-documentation.md): Serve llms.txt and llms-full.txt alongside your docs so AI assistants get real content instead of an empty SPA shell — plus Shelf's own root /llms.txt product index.
- [Troubleshooting](/guide/troubleshooting.md): Symptoms and fixes for the common failure modes: missing docs, broken styling, upload rejections, login problems, and where the useful logs live.