docs(mdbook-htmx): config reference

# Configuration Reference

This document provides a complete reference for all `[output.htmx]` configuration options in `book.toml`.

## Overview

mdbook-htmx is configured in the `[output.htmx]` section of `book.toml`:

```toml
[output.htmx]
version = "1.0"
htmx-version = "2.0.4"
boost = true
```

---

## Schema Reference

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

---

## Core Settings

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `version` | string | - | Configuration schema version |
| `htmx-version` | string | `"2.0.4"` | HTMX library version to bundle |
| `boost` | boolean | `true` | Enable hx-boost on body |
| `swap-strategy` | enum | `"innerHTML"` | Default hx-swap strategy |
| `target` | string | `"#content"` | Default hx-target selector |
| `push-url` | boolean | `true` | Update browser URL on navigation |
| `template-engine` | enum | `"tera"` | Template engine |
| `theme` | string | - | Path to custom theme directory |
| `output-mode` | enum | `"both"` | Output mode |

### Version

Schema version for configuration compatibility:

```toml
[output.htmx]
version = "1.0"
```

### HTMX Version

Controls which HTMX library version is bundled:

```toml
[output.htmx]
htmx-version = "2.0.4"
```

### Swap Strategy

Default `hx-swap` strategy for content replacement:

| Value | Description |
|-------|-------------|
| `innerHTML` | Replace inner HTML of target (default) |
| `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 |

```toml
[output.htmx]
swap-strategy = "innerHTML"
```

### Template Engine

Supported template engines:

| Value | Description |
|-------|-------------|
| `tera` | Tera (Jinja2-like, default) |
| `handlebars` | Handlebars |
| `nunjucks` | Nunjucks |
| `liquid` | Liquid |

```toml
[output.htmx]
template-engine = "tera"
```

### Output Mode

Controls what files are generated:

| Value | Description |
|-------|-------------|
| `full` | Complete pages with layout |
| `fragments` | Content-only partials |
| `both` | Both full pages and fragments (default) |

```toml
[output.htmx]
output-mode = "both"
```

---

## Navigation (`[output.htmx.navigation]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `sidebar-collapse` | boolean | `true` | Enable collapsible sidebar sections |
| `header-nav` | boolean | `true` | Show in-page header navigation |
| `breadcrumbs` | boolean | `true` | Show breadcrumb trail |
| `prev-next` | boolean | `true` | Show previous/next navigation |

```toml
[output.htmx.navigation]
sidebar-collapse = true
header-nav = true
breadcrumbs = true
prev-next = true
```

---

## Authentication (`[output.htmx.authn]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `false` | Enable authentication features |
| `signin-page` | string | `"/auth/signin"` | Public sign-in page path |
| `signin-partial` | string | `"partials/signin.html"` | Sign-in partial template |
| `signout-page` | string | `"/auth/signout"` | Sign-out page path |
| `session-header` | string | `"X-User-Session"` | HTTP header for session token |
| `user-header` | string | `"X-User-ID"` | HTTP header for user identity |
| `provider` | enum | - | Auth provider hint |

### Provider Values

| Value | Description |
|-------|-------------|
| `jwt` | JSON Web Token |
| `session` | Server-side sessions |
| `oauth2` | OAuth 2.0 |
| `saml` | SAML 2.0 |

```toml
[output.htmx.authn]
enabled = true
signin-page = "/auth/signin"
signin-partial = "partials/signin.html"
signout-page = "/auth/signout"
session-header = "X-User-Session"
user-header = "X-User-ID"
provider = "jwt"
```

---

## Authorization (`[output.htmx.authz]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `false` | Enable authorization features |
| `frontmatter-key` | string | `"auth"` | Frontmatter key for auth rules |
| `default-access` | enum | `"public"` | Default access level |
| `denied-partial` | string | `"partials/access-denied.html"` | Access denied template |
| `provider` | enum | `"manifest"` | Authorization provider hint |

### Default Access Levels

| Value | Description |
|-------|-------------|
| `public` | Anyone can access (default) |
| `authenticated` | Logged-in users only |
| `roles` | Specific roles only |

### Provider Values

| Value | Description |
|-------|-------------|
| `manifest` | Manifest-based (default) |
| `spicedb` | SpiceDB/Zanzibar |
| `openfga` | OpenFGA |
| `opa` | Open Policy Agent |

```toml
[output.htmx.authz]
enabled = true
frontmatter-key = "auth"
default-access = "public"
denied-partial = "partials/access-denied.html"
provider = "manifest"
```

---

## Search (`[output.htmx.search]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `true` | Enable search index generation |
| `index-format` | enum | `"json"` | Search index format |
| `heading-split-level` | integer | `3` | Max heading level to index (1-6) |
| `include-body` | boolean | `true` | Include full body text |
| `max-body-length` | integer | `10000` | Max body text length per page |
| `scope-indexes` | boolean | `true` | Generate per-scope indexes |
| `authz-filter` | boolean | `true` | Include auth info for filtering |
| `exclude` | string[] | `[]` | Glob patterns to exclude |

### Index Format

| Value | Description |
|-------|-------------|
| `json` | JSON file (default) |
| `sqlite` | SQLite database |
| `pagefind` | Pagefind format |

```toml
[output.htmx.search]
enabled = true
index-format = "json"
heading-split-level = 3
include-body = true
max-body-length = 10000
scope-indexes = true
authz-filter = true
exclude = ["drafts/*", "internal/*"]
```

### External Search (`[output.htmx.search.external]`)

| Key | Type | Description |
|-----|------|-------------|
| `engine` | enum | External search engine |
| `index-name` | string | Search index/collection name |

#### Engine Values

| Value | Description |
|-------|-------------|
| `meilisearch` | Meilisearch |
| `typesense` | Typesense |
| `algolia` | Algolia |

```toml
[output.htmx.search.external]
engine = "meilisearch"
index-name = "docs"
```

---

## Assets (`[output.htmx.assets]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `hash-files` | boolean | `true` | Add content hash for cache busting |
| `inline-css` | boolean | `false` | Inline critical CSS |
| `copy-htmx` | boolean | `true` | Copy htmx.min.js to output |
| `minify` | boolean | `false` | Minify HTML, CSS, JS |
| `compress` | boolean | `false` | Generate gzip/brotli versions |

```toml
[output.htmx.assets]
hash-files = true
inline-css = false
copy-htmx = true
minify = false
compress = false
```

---

## Scopes (`[output.htmx.scopes]`)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `false` | Enable audience scopes |
| `available` | string[] | `["all"]` | Available scope names |
| `default` | string | `"all"` | Default scope |
| `global-scopes` | string[] | `["all"]` | Scopes in main index |

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

---

## Complete Example

```toml
[book]
title = "Platform Documentation"
authors = ["Platform Team"]
description = "Complete platform reference"
language = "en"

[output.htmx]
version = "1.0"
htmx-version = "2.0.4"
boost = true
swap-strategy = "innerHTML"
target = "#content"
push-url = true
template-engine = "tera"
theme = "my-theme"
output-mode = "both"

[output.htmx.navigation]
sidebar-collapse = true
header-nav = true
breadcrumbs = true
prev-next = true

[output.htmx.authn]
enabled = true
signin-page = "/auth/signin"
signin-partial = "partials/signin.html"
signout-page = "/auth/signout"
provider = "jwt"

[output.htmx.authz]
enabled = true
frontmatter-key = "auth"
default-access = "public"
denied-partial = "partials/access-denied.html"
provider = "manifest"

[output.htmx.search]
enabled = true
index-format = "json"
heading-split-level = 3
include-body = true
max-body-length = 10000
scope-indexes = true
authz-filter = true
exclude = ["drafts/*"]

[output.htmx.search.external]
engine = "meilisearch"
index-name = "platform-docs"

[output.htmx.assets]
hash-files = true
inline-css = false
copy-htmx = true
minify = true
compress = true

[output.htmx.scopes]
enabled = true
available = ["all", "developers", "managers", "sre"]
default = "all"
global-scopes = ["all"]
```

---

## Minimal Example

For a simple setup with defaults:

```toml
[book]
title = "My Docs"

[output.htmx]
version = "1.0"
```

---

## Environment Variables

Configuration can be overridden via environment variables:

| Variable | Config Key |
|----------|------------|
| `MDBOOK_HTMX_BOOST` | `boost` |
| `MDBOOK_HTMX_MINIFY` | `assets.minify` |
| `MDBOOK_HTMX_SEARCH_ENABLED` | `search.enabled` |

```bash
MDBOOK_HTMX_MINIFY=true mdbook build
```

---

## Related Documentation

- [ADR-0014: Configuration Schema Versioning](../adr/0014-configuration-schema-versioning.md)
- [JSON Schema: book-config.schema.json](../schemas/book-config.schema.json)
- [SPEC.md](../SPEC.md)