docs(mdbook-htmx): frontmatter support

# Frontmatter Reference

This document provides a complete reference for all frontmatter keys supported by mdbook-htmx.

## Overview

mdbook-htmx extracts metadata from YAML frontmatter in markdown files. This metadata controls authorization, HTMX behavior, search indexing, and audience scoping.

```yaml
---
auth:
access: roles
roles: [admin, editor]
scopes: [developers, sre]
htmx:
lazy: true
---
# Page Title
```

---

## Schema Reference

Frontmatter is validated against the JSON Schema at:
```
https://schemas.arusty.dev/mdbook-htmx/frontmatter.schema.json
```

---

## Authorization (`auth`)

Controls access requirements for the page.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `access` | enum | `"public"` | Access level: `public`, `authenticated`, or `roles` |
| `roles` | string[] | `[]` | Required roles (when access is `roles`) |
| `fallback` | string | `/auth/access-denied` | Redirect path for unauthorized access |
| `inherit` | boolean | `true` | Inherit parent section's auth settings |

### Examples

**Public page (default):**
```yaml
---
auth:
access: public
---
```

**Authenticated users only:**
```yaml
---
auth:
access: authenticated
---
```

**Role-based access:**
```yaml
---
auth:
access: roles
roles: [admin, editor]
fallback: /docs/access-denied
---
```

**Inherit from parent:**
```yaml
---
auth:
inherit: true # Uses parent section's auth rules
---
```

---

## Audience Scopes (`scopes`)

Controls which audience segments can see the page.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `scopes` | string[] | `["all"]` | Audience scopes this page belongs to |

### Available Scopes

Scopes are defined in `book.toml`:

```toml
[output.htmx.scopes]
available = ["all", "developers", "managers", "sre"]
default = "all"
```

### Examples

**Developers only:**
```yaml
---
scopes: [developers]
---
```

**Multiple audiences:**
```yaml
---
scopes: [developers, sre]
---
```

**All audiences (default):**
```yaml
---
scopes: [all]
---
```

---

## HTMX Behavior (`htmx`)

Controls HTMX-specific rendering and behavior.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `lazy` | boolean | `false` | Load content on reveal (hx-trigger="revealed") |
| `preload` | boolean | `false` | Preload on hover |
| `cache` | integer | `0` | Cache-Control max-age in seconds |
| `swap` | enum | `"innerHTML"` | Override default hx-swap strategy |
| `pushUrl` | boolean | `true` | Update browser URL on navigation |
| `boost` | boolean | `true` | Enable hx-boost for this page |

### Swap Strategies

| Value | Description |
|-------|-------------|
| `innerHTML` | Replace inner HTML of target |
| `outerHTML` | Replace entire target element |
| `beforebegin` | Insert before target |
| `afterbegin` | Insert at start of target |
| `beforeend` | Insert at end of target |
| `afterend` | Insert after target |
| `delete` | Delete target |
| `none` | No swap (for side effects only) |

### Examples

**Lazy loading:**
```yaml
---
htmx:
lazy: true
preload: false
---
```

**Aggressive caching:**
```yaml
---
htmx:
cache: 86400 # 24 hours
preload: true
---
```

**Custom swap:**
```yaml
---
htmx:
swap: outerHTML
pushUrl: false
---
```

---

## Search Configuration (`search`)

Controls how the page is indexed for search.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `indexed` | boolean | `true` | Include in search index |
| `weight` | number | `1.0` | Ranking weight (higher = more prominent) |
| `keywords` | string[] | `[]` | Additional search keywords |
| `excerpt` | string | (auto) | Custom excerpt for search results |
| `excludeHeadings` | boolean | `false` | Exclude headings from index |

### Examples

**High-priority page:**
```yaml
---
search:
indexed: true
weight: 2.0
keywords: [quickstart, tutorial, getting-started]
---
```

**Exclude from search:**
```yaml
---
search:
indexed: false
---
```

**Custom excerpt:**
```yaml
---
search:
excerpt: "Complete API reference for the authentication module"
---
```

---

## Page Metadata (`meta`)

Standard page metadata.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `title` | string | (from H1) | Page title |
| `description` | string | (from excerpt) | Meta description |
| `template` | string | `"page.html"` | Custom template override |
| `draft` | boolean | `false` | Mark as draft (excluded from build) |
| `publishDate` | date | (none) | Publish date (for scheduled content) |
| `lastModified` | date | (auto) | Last modification date |

### Examples

**Custom metadata:**
```yaml
---
meta:
title: "Getting Started Guide"
description: "Learn how to install and configure mdbook-htmx"
template: "tutorial.html"
---
```

**Draft content:**
```yaml
---
meta:
draft: true
---
```

---

## Complete Example

```yaml
---
meta:
title: "Admin API Reference"
description: "Complete reference for the administration API"
template: "api-reference.html"

auth:
access: roles
roles: [admin, developer]
fallback: /docs/access-denied

scopes: [developers, sre]

htmx:
lazy: false
preload: true
cache: 3600

search:
indexed: true
weight: 1.5
keywords: [api, admin, reference, endpoints]
---

# Admin API Reference

This section documents the administration API...
```

---

## Validation

Frontmatter is validated at build time. Invalid frontmatter produces clear error messages:

```
error: auth.access is 'roles' but no roles specified
--> src/admin/config.md:3
|
1 | ---
2 | auth:
3 | access: roles
| ^^^^^ missing 'roles' field
4 | ---
|

help: Add 'roles: [role1, role2]' to the auth section
```

### Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Unknown scope 'X'` | Scope not in `scopes.available` | Add to book.toml or fix typo |
| `Missing roles field` | `access: roles` without roles list | Add `roles: [...]` |
| `Invalid swap strategy` | Typo in swap value | Use valid strategy name |
| `Unknown field` | Typo in field name | Check spelling |

---

## Defaults

When frontmatter is omitted or incomplete, these defaults apply:

```yaml
auth:
access: public
roles: []
fallback: /auth/access-denied
inherit: true

scopes: [all]

htmx:
lazy: false
preload: false
cache: 0
swap: innerHTML
pushUrl: true
boost: true

search:
indexed: true
weight: 1.0
keywords: []
excludeHeadings: false

meta:
draft: false
```

---

## Related Documentation

- [ADR-0013: Frontmatter Schema and Validation](../adr/0013-frontmatter-schema-and-validation.md)
- [ADR-0003: Authorization Metadata via Manifest](../adr/0003-authorization-via-manifest.md)
- [JSON Schema: frontmatter.schema.json](../schemas/frontmatter.schema.json)