---
url: /guide/base-path-rewriting.md
---
# Base Path Rewriting

Shelf automatically rewrites the VitePress base path so that documentation sites built with the default `base: '/'` work correctly when served under a product/version URL like `/configuration/v5/`.

## Why This Is Needed

VitePress bakes the `base` path into the build output at build time. A site built with `base: '/'` generates links like:

```html
<link href="/assets/style.a1b2c3d4.css">
<script src="/assets/app.x7y8z9.js">
```

When Shelf serves these files under `/configuration/v5/`, the browser would request `/assets/style.a1b2c3d4.css` — without the product/version prefix. That request would fail.

Shelf solves this by detecting the original base path and rewriting it in all text-based responses before sending them to the browser.

## How Detection Works

When a product/version is first accessed, Shelf reads the `index.html` and looks for the first `href` attribute pointing to `assets/`. The path prefix before `assets/` is the original base path.

For example:

* `href="/assets/style.css"` → original base is `/`
* `href="/docs/assets/style.css"` → original base is `/docs/`
* `href="/__shelf__/assets/style.css"` → original base is `/__shelf__/`

The detected base is cached per product/version.

## What Gets Rewritten

Shelf rewrites different file types with different strategies:

### HTML Files

Attribute values starting with the original base path are rewritten:

| Before | After |
|---|---|
| `href="/assets/style.css"` | `href="/configuration/v5/assets/style.css"` |
| `src="/assets/app.js"` | `src="/configuration/v5/assets/app.js"` |
| `href="/guide/getting-started.html"` | `href="/configuration/v5/guide/getting-started.html"` |

External URLs (`href="https://..."`) and anchors (`href="#section"`) are not affected.

Additionally, the VitePress site data blob (`__VP_SITE_DATA__`) contains a `"base":"/"` property that is rewritten to `"base":"/configuration/v5/"`. This is critical for the client-side Vue router to work correctly.

### CSS Files

`url()` references are rewritten:

| Before | After |
|---|---|
| `url(/assets/font.woff2)` | `url(/configuration/v5/assets/font.woff2)` |

### JavaScript Files

JS rewriting is the most delicate part. VitePress generates minified JavaScript where the base path appears in specific patterns. Shelf targets these precisely to avoid false positives:

**Pattern 1 — Router base constant:**

```js
// Before:
){const n="/";t=pi(t.slice(n.length)
// After:
){const n="/configuration/v5/";t=pi(t.slice(n.length)
```

**Pattern 2 — Module preload URL builder:**

```js
// Before:
=function(e){return"/"+e}
// After:
=function(e){return"/configuration/v5/"+e}
```

**Pattern 3 — Search index document IDs:**

The local search index contains document paths like `"/guide/caching.html#caching"`. These are rewritten using a broader string replacement, but only in files that contain search index data (identified by the presence of `"documentIds"`).

::: warning Important
The JS patterns are specific to VitePress 1.x. If a future VitePress version changes the minified output structure, these patterns may need updating. If you encounter broken client-side navigation after a VitePress upgrade, this is the first place to investigate.
:::

## When Original Base Is Not `/`

If the original base is a unique string (e.g., `/__shelf__/` or `/docs/`), Shelf uses a simple string replacement across all text files. This is completely safe because the original base is unique enough to have no false positives.

This means you have two options for building your docs:

1. **Default `base: '/'`** — zero configuration, Shelf handles everything with targeted rewriting
2. **Custom `base`** (e.g., `base: '/__shelf__/'`) — even safer, simple string replacement with no pattern matching needed

## What Is Not Rewritten

* **Binary files** (images, fonts, WebAssembly) are served as-is
* **Plain text files** (`llms.txt`, `llms-full.txt`) are served as-is
* **External URLs** (`https://...`, `//cdn...`) are never modified
* **Anchor links** (`#section`) are never modified

---

---
url: /guide/caching.md
---
# Caching

Shelf applies caching headers to optimize delivery of static assets.

## Immutable Assets

VitePress generates CSS and JavaScript files with content hashes in their filenames (e.g., `style.a1b2c3d4.css`). These files never change — if the content changes, the filename changes too.

Shelf detects these hashed filenames and serves them with aggressive cache headers:

```
Cache-Control: public, max-age=31536000, immutable
```

This tells browsers and CDNs to cache these files for one year without revalidation.

## HTML Files

HTML files are served without explicit cache headers, meaning browsers will revalidate on each request. This ensures users always see the latest content after a new version is deployed.

## LLM Files

`llms.txt` and `llms-full.txt` are plain text files served with default caching behavior, similar to HTML files.

---

---
url: /guide/configuration.md
---
# Configuration

Shelf requires minimal configuration. Most setups work with just Docker volume mounts and a few environment variables.

## Options

Configuration is done via environment variables using the ASP.NET Core configuration pattern (`Shelf__PropertyName`) or via `appsettings.json`:

| Option | Env Variable | Default | Description |
|---|---|---|---|
| `DocsRoot` | `Shelf__DocsRoot` | `/data/docs` | Root directory for documentation files |
| `ConfigRoot` | `Shelf__ConfigRoot` | `/data/config` | Root directory for [product config](./product-registration.md) files |
| `PathBase` | `Shelf__PathBase` | *(empty)* | Global URL prefix for running under a sub-path |
| `VersionPattern` | `Shelf__VersionPattern` | `^v?\d+(\.\d+(\.\d+(-[\w.]+)?)?)?$` | Regex pattern to identify version directories |
| `EnableLandingPage` | `Shelf__EnableLandingPage` | `false` | Show a product overview page at the root URL |
| `ApiKey` | `Shelf__ApiKey` | *(empty)* | API key for [upload endpoint](./upload-api.md). Empty = upload disabled |
| `MaxUploadSizeBytes` | `Shelf__MaxUploadSizeBytes` | `104857600` | Maximum upload size in bytes (100 MB) |

## PathBase

When Shelf runs behind a reverse proxy under a sub-path (e.g., `example.com/docs/` instead of `docs.example.com/`), set `PathBase` to the prefix:

```yaml
environment:
  - Shelf__PathBase=/docs
```

All routes, redirects, and base path rewriting automatically include the prefix:

| PathBase | Docs URL | API URL |
|----------|----------|---------|
| *(empty)* | `/configuration/v5/` | `/api/products` |
| `/docs` | `/docs/configuration/v5/` | `/docs/api/products` |

## Landing Page

When `EnableLandingPage` is `true`, Shelf renders a product overview page at the root URL (`/` or `{PathBase}/`). The page shows cards for all [registered products](./product-registration.md) that have at least one deployed version. Clicking a product opens its documentation in a new tab.

```yaml
environment:
  - Shelf__EnableLandingPage=true
```

Only products with a config file and deployed versions appear on the landing page. Products deployed manually (without registration) are still accessible via direct URL but won't be listed.

## Version Pattern

By default, Shelf recognizes a wide range of version formats:

| Format | Examples |
|--------|----------|
| Major only | `v1`, `v5`, `v10` |
| Major.Minor | `v5.1`, `v5.2`, `5.2` |
| Full SemVer | `v5.2.0`, `5.2.0` |
| Pre-release | `v6.0.0-beta.1`, `v6.0.0-rc.1` |

The `v` prefix is optional. Directories that don't match the pattern are ignored:

```
/data/docs/configuration/
├── v5.1.0/                ← recognized
├── v5.2.0/                ← recognized
├── v6.0.0-beta.1/         ← recognized (pre-release)
├── assets/                ← ignored
└── .hidden/               ← ignored
```

### Version Sorting

Versions are sorted numerically by Major, Minor, and Patch. The **latest** version is determined as follows:

1. **Stable versions** (without pre-release label) are always preferred
2. Among stable versions, the highest Major.Minor.Patch wins
3. If only pre-release versions exist, the highest one is used as latest

Example: With `v5.2.0`, `v6.0.0-beta.1`, and `v5.1.0`, the latest is `v5.2.0` — because `v6.0.0-beta.1` is a pre-release.

::: tip GitVersion / SemVer
Shelf works well with [GitVersion](https://gitversion.net/) or any SemVer-based versioning. Use the version output from your CI pipeline directly as the version directory name.
:::

### Customizing the Version Pattern

If you need a stricter or different versioning scheme, override the pattern:

```yaml
environment:
  # Only allow full SemVer with v prefix
  - Shelf__VersionPattern=^v\d+\.\d+\.\d+$

  # Only major versions
  - Shelf__VersionPattern=^v\d+$
```

---

---
url: /guide/docker.md
---
# Docker

Shelf runs as a Docker container with documentation and configuration files mounted as volumes.

## Basic Setup

```yaml
# docker-compose.yml
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
```

Two volumes:

* **Docs volume** — writable, so the [Upload API](./upload-api.md) can deploy versions
* **Config volume** — read-only, contains [product registration](./product-registration.md) files

If you don't use the Upload API and only deploy manually, you can mount the docs volume as `:ro` (read-only).

## Volume Mounting

### Single Volume

The simplest approach. All products live in one volume:

```yaml
volumes:
  - docs-data:/data/docs
  - config-data:/data/config:ro
```

### One Volume Per Product

Useful when products are deployed independently:

```yaml
volumes:
  - config-docs:/data/docs/configuration
  - caps-docs:/data/docs/capabilities
```

### Host Directory

For development or simple setups, mount host directories directly:

```yaml
volumes:
  - /srv/docs:/data/docs
  - /srv/config:/data/config:ro
```

## Environment Variables

See [Configuration](./configuration.md) for all options. The most important ones for Docker:

| Variable | Default | Description |
|---|---|---|
| `Shelf__DocsRoot` | `/data/docs` | Root directory for documentation files |
| `Shelf__ConfigRoot` | `/data/config` | Root directory for product config files |
| `Shelf__ApiKey` | *(empty)* | API key for upload endpoint. Empty = upload disabled |
| `Shelf__PathBase` | *(empty)* | Global URL prefix (e.g. `/docs`) |

## Building From Source

```bash
docker compose build
```

Or build the image directly:

```bash
docker build -t cocoar/shelf .
```

---

---
url: /guide/getting-started.md
---
# Getting Started

Shelf is a static documentation hosting platform for Cocoar products. It serves VitePress-generated documentation with support for multiple products and multiple versions per product.

## What It Does

* Serves static HTML/CSS/JS files from a mounted volume
* Routes requests to the correct product and version
* Automatically determines the "latest" version per product
* Provides an [Upload API](./upload-api.md) for deploying docs from CI/CD pipelines
* Caches version information and invalidates on filesystem changes

## Quick Start

### 1. Run with Docker

```yaml
# docker-compose.yml
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
```

```bash
docker compose up -d
```

### 2. Add Documentation

**Option A: Upload API** (recommended for CI/CD)

Register the product, then upload a ZIP:

```bash
# Create product config
echo '{"name": "configuration", "source": "upload"}' > /data/config/products/configuration.json

# Upload docs
curl -X POST \
  -H "Authorization: Bearer $SHELF_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @docs.zip \
  http://localhost/api/products/configuration/versions/v5
```

See [Product Registration](./product-registration.md) and [Upload API](./upload-api.md) for details.

**Option B: Manual** (copy files directly)

Place your VitePress build output in the volume:

```
/data/docs/
└── configuration/
    └── v5/
        ├── index.html
        ├── assets/
        ├── guide/
        ├── llms.txt
        └── llms-full.txt
```

### 3. Access Your Docs

Your documentation is now available at:

* `http://localhost/configuration/` — latest version (redirects to v5)
* `http://localhost/configuration/v5/` — specific version

---

---
url: /guide/how-it-works.md
---
# How It Works

Shelf is intentionally simple. It's an ASP.NET Core application that serves static files from a volume with smart URL routing and automatic base path rewriting.

## Volume Structure

Shelf expects documentation files organized by product and version:

```
/data/docs/
├── configuration/
│   ├── v4/
│   │   ├── index.html
│   │   ├── assets/
│   │   └── ...
│   └── v5/
│       ├── index.html
│       ├── assets/
│       └── ...
├── capabilities/
│   └── v1/
│       └── ...
└── filesystem/
    └── v1/
        └── ...
```

Each product is a directory. Each version within a product is a subdirectory matching the pattern `v{number}` (e.g., `v1`, `v5`, `v12`).

## Version Detection

Shelf scans the filesystem to determine available versions. The **highest version number** is automatically the "latest". There is no manifest file or configuration needed.

When a request for `/configuration/` comes in (no version), Shelf redirects to the latest version:

1. Identifies `configuration` as the product
2. Scans its subdirectories for version folders
3. Picks the highest version (e.g., `v5`)
4. Redirects to `/configuration/v5/`

Requests with an explicit version (e.g., `/configuration/v5/guide/getting-started.html`) are served directly.

## Base Path Rewriting

VitePress bakes the `base` path into all generated files at build time. Normally, you'd have to build your docs with the exact base path matching where they'll be hosted (e.g., `base: '/configuration/v5/'`).

**Shelf removes this requirement.** You can build your VitePress site with the default `base: '/'` and Shelf rewrites all paths on the fly when serving responses. See [Base Path Rewriting](./base-path-rewriting.md) for details on how this works.

## Automatic Cache Invalidation

Shelf watches the docs directory for changes using [Cocoar.FileSystem](https://github.com/cocoar-dev/Cocoar.FileSystem)'s `ResilientFileSystemMonitor`. When a new version directory is created or removed, the cached version list for that product is automatically invalidated.

This means deploying a new version is instant — whether via the [Upload API](./upload-api.md) or by copying files directly into the volume. Shelf picks it up without a restart.

We use `ResilientFileSystemMonitor` instead of .NET's raw `FileSystemWatcher` because it provides:

* **Automatic recovery** — if the docs volume is temporarily unavailable (Docker mount issues, network glitches), the monitor recovers automatically instead of silently dying
* **Debouncing** — rapid filesystem changes during a deployment are consolidated into a single cache invalidation
* **Audit timer** — periodically verifies that no events were missed, a known issue with `FileSystemWatcher` under high load
* **Polling fallback** — if native filesystem events aren't available (certain network shares, Docker volume edge cases), the monitor falls back to polling automatically

---

---
url: /guide/llm-documentation.md
---
# LLM Documentation

When AI assistants (Claude, ChatGPT, etc.) fetch a documentation page, they receive the raw HTML but typically don't execute JavaScript. Single-page applications and JavaScript-heavy frameworks render very little useful content without JS. This means an AI fetching your docs may get almost nothing.

The solution: provide plain-text versions of your documentation that are optimized for LLM consumption.

## The Convention

The emerging standard (see [llmstxt.org](https://llmstxt.org/)) is to serve two plain-text files alongside your documentation:

| File | Purpose |
|------|---------|
| `llms.txt` | Short summary — product description, links, and table of contents |
| `llms-full.txt` | Complete documentation as plain Markdown |

These files should be served at the root of your documentation:

```
https://docs.example.com/myproduct/v5/llms.txt
https://docs.example.com/myproduct/v5/llms-full.txt
```

Shelf serves these files like any other static file — just include them in your deployment archive.

## Making the Files Discoverable

### Link Tags in the HTML Head

Add `<link>` tags to your HTML `<head>` so AI tools can find the LLM-optimized versions when they fetch any page:

```html
<link rel="alternate" type="text/plain" href="/llms.txt"
      title="LLM documentation (summary)">
<link rel="alternate" type="text/plain" href="/llms-full.txt"
      title="LLM documentation (full)">
```

The leading `/` makes the path root-relative. Shelf's [base path rewriting](./base-path-rewriting.md) rewrites it to include the correct product/version prefix (e.g., `/configuration/v5/llms.txt`).

This is similar to how RSS feeds are discoverable via `<link rel="alternate" type="application/rss+xml">`.

### Visible Link

Additionally, add a visible link in your navigation or footer. This helps users who want to share documentation with AI assistants, and some AI tools also follow visible links. For example, the [Marten documentation](https://martendb.io/) includes a "LLM Friendly Docs" link in the top navigation.

### Using Both

We recommend using both approaches. The `<link>` tags are what AI tools parse programmatically, while the visible link helps human users discover the feature.

## VitePress Setup

For VitePress projects, the [`vitepress-plugin-llms`](https://github.com/okineadev/vitepress-plugin-llms) plugin handles everything automatically. It's used by major projects including Vite, Vue.js, and Vitest.

### Installation

```bash
npm install -D vitepress-plugin-llms
```

### Configuration

```ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import llmstxt from 'vitepress-plugin-llms'

export default defineConfig({
  // Link tags for discoverability
  head: [
    ['link', {
      rel: 'alternate',
      type: 'text/plain',
      href: '/llms.txt',
      title: 'LLM documentation (summary)'
    }],
    ['link', {
      rel: 'alternate',
      type: 'text/plain',
      href: '/llms-full.txt',
      title: 'LLM documentation (full)'
    }],
  ],

  // Plugin generates llms.txt and llms-full.txt during build
  vite: {
    plugins: [llmstxt()],
  },

  themeConfig: {
    nav: [
      // Visible link in the navigation bar
      { text: 'LLM Docs', link: '/llms-full.txt', target: '_blank' },
    ],
  },
})
```

That's it. When you run `vitepress build`, the plugin:

1. Scans for Markdown pages in your project
2. Generates `llms.txt` (summary with links) and `llms-full.txt` (complete documentation)
3. Includes them in the build output

The generated files end up in your deployment archive automatically.

::: tip Verify Coverage
After building, check the generated `llms-full.txt` to make sure all your pages are included. By default, the plugin may exclude some files it considers unnecessary. If pages are missing, try adjusting the plugin options:

```ts
llmstxt({
  excludeUnnecessaryFiles: false,  // include all pages
  ignoreFiles: ['changelog.md'],   // explicitly exclude specific files
})
```

See the [plugin documentation](https://github.com/okineadev/vitepress-plugin-llms) for all available options.
:::

### Shelf Integration

Shelf's [base path rewriting](./base-path-rewriting.md) takes care of rewriting the `href` values in the `<link>` tags to include the correct product/version prefix. No additional configuration needed.

## Other Frameworks

For non-VitePress documentation, the approach is the same:

1. Generate `llms.txt` and `llms-full.txt` as part of your build process
2. Include them in the deployment archive alongside your HTML
3. Add `<link>` tags and a visible link for discoverability

How you generate the files depends on your framework and tooling. The content should be clean, readable Markdown without framework-specific syntax.

---

---
url: /guide/product-registration.md
---
# Product Registration

Before documentation can be deployed via the [Upload API](./upload-api.md), a product must be registered. Registration is done by placing a JSON config file in the config directory.

## Config Directory

Product config files live in `{ConfigRoot}/products/`, one file per product:

```
/data/config/
└── products/
    ├── configuration.json
    ├── capabilities.json
    └── filesystem.json
```

## Config File Format

Each JSON file describes one product:

```json
{
  "name": "configuration",
  "displayName": "Cocoar.Configuration",
  "description": "Reactive configuration for .NET",
  "source": "upload"
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Product identifier, used in URLs and API calls |
| `displayName` | No | Human-readable name for API responses |
| `description` | No | Short description of the product |
| `source` | No | Deployment source type. Default: `"upload"` |

::: tip
The `name` field determines the URL path, not the filename. By convention, keep both in sync (e.g., `configuration.json` with `"name": "configuration"`).
:::

## Live Reload

Config files are loaded at startup and monitored for changes. When you add, modify, or remove a config file, Shelf picks up the change automatically — no restart needed.

## Why Registration?

Product registration is required for the Upload API to prevent accidental creation of arbitrary products. Without registration, a typo in a CI pipeline (`configration` instead of `configuration`) would silently create a new product.

Manual deployment (copying files directly into the docs volume) does **not** require registration — Shelf serves any product directory it finds, regardless of whether a config file exists.

## API Integration

Registered products are visible via the API:

```bash
# List all registered products with their versions
curl https://docs.cocoar.dev/api/products
```

```json
[
  {
    "name": "configuration",
    "displayName": "Cocoar.Configuration",
    "description": "Reactive configuration for .NET",
    "source": "upload",
    "latest": "v5",
    "versions": ["v5", "v4"]
  }
]
```

---

---
url: /guide/troubleshooting.md
---
# Troubleshooting

## Documentation Not Showing Up

**Check the volume mount.** Verify that the files are actually visible inside the container:

```bash
docker exec shelf ls -la /data/docs/
docker exec shelf ls -la /data/docs/configuration/
```

**Check the version directory name.** Shelf only recognizes directories matching the version pattern (default: `v1`, `v2`, etc.). A directory named `latest`, `main`, or `1.0` will not be detected.

## Wrong Version Served as "Latest"

Shelf determines the latest version by sorting version numbers numerically. `v10` is higher than `v9`, not lower (it's not alphabetical sorting).

Verify which versions Shelf sees:

```bash
docker exec shelf ls /data/docs/configuration/
```

## Page Loads But Navigation Is Broken

This is most likely a **base path rewriting** issue. Shelf rewrites the VitePress base path in HTML, CSS, and JavaScript files. If the rewriting misses something, the page may render initially but client-side navigation (clicking sidebar links) fails.

**Check the site data base path.** Open the browser DevTools console and run:

```js
__VP_SITE_DATA__.base
```

This should return the full product/version path (e.g., `"/configuration/v5/"`). If it returns `"/"`, the site data rewriting is not working.

**Check the JavaScript base path.** In the Network tab, find the `framework.*.js` file and search for the base path. It should contain your product/version path, not `"/"`.

**VitePress version mismatch.** The JavaScript rewriting targets specific patterns in VitePress 1.x minified output. If you've upgraded VitePress and navigation breaks, the minified patterns may have changed. See [Base Path Rewriting](./base-path-rewriting.md) for details on which patterns Shelf targets.

## CSS/Fonts Not Loading

**Check the CSS `url()` paths.** In DevTools Network tab, look for 404 errors on font or CSS files. If the paths still have `"/"` as the prefix instead of `"/configuration/v5/"`, the CSS rewriting is not working.

This can happen if the CSS file's content type is not detected as `text/css`. Check that the file extension is `.css`.

## Files Exist But Return 404

**Check file extensions.** Shelf appends `index.html` to requests without a file extension. If your files have non-standard extensions, they may not be found.

**Check path traversal protection.** Shelf blocks any resolved path that falls outside the docs root directory. If your symlinks or relative paths point outside the volume, they will be blocked.

## Overlapping Volume Mounts

Docker supports mounting multiple volumes at nested paths. If you have both a general mount and a product-specific mount:

```yaml
volumes:
  - docs-data:/data/docs
  - config-docs:/data/docs/configuration
```

The more specific mount (`/data/docs/configuration`) takes precedence and **hides** any `configuration/` directory that exists in the general `docs-data` volume. This is standard Linux mount behavior and is independent of the order in the compose file.

If a product's documentation is unexpectedly empty or outdated, check whether someone has added a more specific volume mount that shadows the expected data.

## Container Restarts

Shelf caches two things in memory:

1. **Version lists** per product — invalidated automatically via `FileSystemWatcher`
2. **Detected base paths** per product/version — cached indefinitely

If you suspect stale data after a problematic deployment, restarting the container clears all caches:

```bash
docker compose restart shelf
```

---

---
url: /guide/upload-api.md
---
# Upload API

Shelf provides an HTTP API for deploying documentation versions. This is designed for CI/CD pipelines — analogous to `nuget push` or `docker push`.

## Prerequisites

1. The product must be [registered](./product-registration.md) via a config file
2. An API key must be [configured](./configuration.md) (`Shelf__ApiKey`)

If no API key is configured, the upload endpoint returns `503 Service Unavailable`.

## Uploading a Version

```bash
curl -X POST \
  -H "Authorization: Bearer $SHELF_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @docs.zip \
  https://docs.cocoar.dev/api/products/configuration/versions/v6
```

The ZIP file should contain the VitePress build output with `index.html` at the root:

```
docs.zip
├── index.html
├── assets/
│   ├── style.a1b2c3.css
│   └── app.d4e5f6.js
├── guide/
│   └── getting-started.html
├── llms.txt
└── llms-full.txt
```

### What Happens

1. API key is validated
2. Product registration is checked (must exist in config)
3. Version format is validated against the [version pattern](./configuration.md#version-pattern) (supports SemVer: `v5`, `v5.2`, `v5.2.0`, `v5.2.0-beta.1`)
4. ZIP is extracted to a temporary directory
5. Validation: `index.html` must exist at the root
6. Atomic move to `/data/docs/{product}/{version}/`
7. ManifestService detects the new version automatically
8. Response: `201 Created`

Re-uploading an existing version replaces it atomically.

## CI/CD Integration

### Setup

1. Add `SHELF_API_KEY` as a repository secret in GitHub
2. Ensure the product is [registered](./product-registration.md) on the server
3. Add a deploy job to your workflow

### GitHub Actions with GitVersion

```yaml
name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: GitVersion
        id: version
        uses: gittools/actions/gitversion/execute@v3

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Build
        working-directory: website
        run: npm ci && npx vitepress build

      - name: Package
        run: cd website/.vitepress/dist && zip -r $GITHUB_WORKSPACE/docs.zip .

      - name: Deploy to Shelf
        env:                                            # [!code highlight]
          KEY: ${{ secrets.SHELF_API_KEY }}              # [!code highlight]
          VER: ${{ steps.version.outputs.major }}.${{ steps.version.outputs.minor }} # [!code highlight]
        run: |
          curl -f -X POST \
            -H "Authorization: Bearer $KEY" \
            -H "Content-Type: application/zip" \
            --data-binary @$GITHUB_WORKSPACE/docs.zip \
            https://docs.cocoar.dev/api/products/configuration/versions/v$VER
```

::: tip Version Format
Choose what makes sense for your docs. Use the GitVersion output variables in the upload URL:

* **Major only** → `v5` (use `outputs.major`)
* **Major.Minor** → `v5.2` (recommended, use `outputs.major` + `outputs.minor`)
* **Full SemVer** → `v5.2.0` (use `outputs.majorMinorPatch`)
  :::

### Manual Trigger Variant

Replace the `on:` section to allow manual deploys with a version input:

```yaml
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version (e.g. v5.2)'
        required: true
```

Then use the `inputs.version` variable instead of the GitVersion output in the `env` section.

### Key Points

* **ZIP from inside the dist directory** — `cd .vitepress/dist && zip -r ... .` so `index.html` is at the root
* **Use `curl -f`** — fails the step on HTTP errors (4xx/5xx)
* **Re-upload replaces atomically** — safe to re-run the pipeline
* **Pre-release versions are never "latest"** — visitors are redirected to the highest stable version

## API Endpoints

### List Products

```
GET /api/products
```

Returns all registered products with their version information. No authentication required.

```json
[
  {
    "name": "configuration",
    "displayName": "Cocoar.Configuration",
    "description": "Reactive configuration for .NET",
    "source": "upload",
    "latest": "v5.2.0",
    "versions": ["v5.2.0", "v5.1.0", "v5.0.0"]
  }
]
```

### List Versions

```
GET /api/products/{product}/versions
```

Returns version information for a specific product. No authentication required.

```json
{
  "name": "configuration",
  "latest": "v5.2.0",
  "versions": ["v5.2.0", "v5.1.0", "v5.0.0"]
}
```

### Upload Version

```
POST /api/products/{product}/versions/{version}
```

Uploads a ZIP file as a new documentation version. Requires `Authorization: Bearer {key}` header.

## Error Responses

| Status | When |
|--------|------|
| `201` | Successfully deployed |
| `400` | Invalid version format, corrupt ZIP, or missing `index.html` |
| `401` | Missing or invalid API key |
| `404` | Product not registered |
| `409` | Concurrent upload for the same product/version |
| `413` | ZIP exceeds maximum upload size |
| `503` | No API key configured (upload disabled) |

## Security

* **Authentication**: Bearer token checked against the configured API key
* **ZIP-Slip protection**: All extracted paths are validated to stay within the target directory
* **Atomic deployment**: Files are extracted to a temp directory, validated, then moved — Shelf never serves a half-extracted state
* **Concurrent upload protection**: Simultaneous uploads for the same product/version return `409 Conflict`
* **Size limit**: Configurable via `MaxUploadSizeBytes` (default: 100 MB)

---

---
url: /guide/url-routing.md
---
# URL Routing

Shelf routes requests based on the URL structure. Every URL starts with a product name, optionally followed by a version.

## Routing Rules

| URL | Behavior |
|---|---|
| `/configuration/` | **Redirect** to latest stable version (e.g., `/configuration/v5.2.0/`) |
| `/configuration/v5.2.0/` | Serve `v5.2.0/index.html` |
| `/configuration/v5.2.0/guide/getting-started.html` | Serve `v5.2.0/guide/getting-started.html` |
| `/configuration/v5.2.0/llms.txt` | Serve `v5.2.0/llms.txt` |

## Latest Version Redirect

When a URL has no explicit version (e.g., `/configuration/` or `/configuration/guide/getting-started.html`), Shelf **redirects** (HTTP 302) to the latest version URL.

This redirect is necessary because VitePress's client-side router needs the URL to match the base path. A transparent proxy would cause the URL in the browser (`/configuration/`) to differ from the base path in the JavaScript (`/configuration/v5/`), breaking client-side navigation.

## How "Latest" Is Determined

Shelf scans the product directory for subdirectories matching the [version pattern](./configuration.md#version-pattern) and picks the **highest stable version**.

* Sorting is **numeric** by Major.Minor.Patch: `v5.2.0` > `v5.1.0` > `v5.0.0`
* **Stable versions are preferred** over pre-releases: if both `v5.2.0` and `v6.0.0-beta.1` exist, the latest is `v5.2.0`
* If only pre-release versions exist, the highest one is used

## Version Detection

The first path segment after the product name is checked against the version pattern:

* `/configuration/v5.2.0/...` — matches version pattern → explicit version, serve directly
* `/configuration/guide/...` — does not match → redirect to latest

## VitePress Base Path

VitePress bakes the `base` path into the build output at build time. Shelf handles this automatically through [Base Path Rewriting](./base-path-rewriting.md) — you do **not** need to set a specific `base` in your VitePress config.

Just build your docs normally:

```bash
npx vitepress build
```

Shelf detects the original base path and rewrites it to match the product/version URL when serving responses.