v1.0.0

Shelf v1.0.0

Shelf your Docs. Static documentation hosting for Cocoar products.

Shelf is an ASP.NET Core application that serves VitePress-generated documentation with multi-product and multi-version support. Deploy new versions without touching old ones — just upload a ZIP from your CI/CD pipeline.

Highlights

Upload API

Deploy documentation directly from CI/CD pipelines via HTTP POST. No SSH, no file copying — just curl a ZIP to the API endpoint.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @docs.zip \
  https://docs.example.com/api/products/myproduct/versions/v1.0.0

SemVer Versioning

Full semantic versioning support: v5, v5.2, v5.2.0, v5.2.0-beta.1. Pre-release versions are accessible but never served as "latest" — visitors are always redirected to the highest stable version.

Product Registration

Explicit product registration via JSON config files with live-reload. Control which products are available for upload and visible on the landing page.

Base Path Rewriting

VitePress sites built with default base: '/' work out of the box. Shelf rewrites HTML, CSS, and JS responses on the fly to match the product/version URL structure.

Landing Page

Optional product overview page at the root URL listing all registered products with their versions.

Features

• Multi-Product — Host documentation for multiple products under one domain
• Multi-Version — Deploy new versions without touching old ones
• Upload API — ZIP upload with atomic deployment, ZIP-Slip protection, and per-version locking
• SemVer — Supports v5, v5.2, v5.2.0, v5.2.0-beta.1
• API Key Auth — Bearer token authentication for upload endpoint
• Base Path Rewriting — Automatic for VitePress (HTML, CSS, JS)
• Resilient File Monitoring — Powered by Cocoar.FileSystem
• Immutable Asset Caching — Hashed assets served with 1-year cache headers
• Landing Page — Optional product overview at root URL
• PathBase — Configurable global URL prefix for sub-path hosting
• LLM Documentation — Serve llms.txt and llms-full.txt for AI-friendly docs

API Endpoints

Method	Path	Auth	Description
GET	/api/products	No	List all products with versions
GET	/api/products/{product}/versions	No	Versions of a product
POST	/api/products/{product}/versions/{version}	Bearer	Upload ZIP as new version

Quick Start

services:
  shelf:
    image: ghcr.io/cocoar-dev/shelf:latest
    ports:
      - "80:8080"
    volumes:
      - docs-data:/data/docs
      - config-data:/data/config:ro
    environment:
      - Shelf__ApiKey=${SHELF_API_KEY:-}
    restart: unless-stopped

Documentation

Full documentation: docs.cocoar.dev/shelf

License

Apache-2.0