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.

---
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):

---
auth:
  access: public
---

Authenticated users only:

---
auth:
  access: authenticated
---

Role-based access:

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

Inherit from parent:

---
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:

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

Examples

Developers only:

---
scopes: [developers]
---

Multiple audiences:

---
scopes: [developers, sre]
---

All audiences (default):

---
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:

---
htmx:
  lazy: true
  preload: false
---

Aggressive caching:

---
htmx:
  cache: 86400  # 24 hours
  preload: true
---

Custom swap:

---
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:

---
search:
  indexed: true
  weight: 2.0
  keywords: [quickstart, tutorial, getting-started]
---

Exclude from search:

---
search:
  indexed: false
---

Custom excerpt:

---
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:

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

Draft content:

---
meta:
  draft: true
---

---

Complete Example

---
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:

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-0003: Authorization Metadata via Manifest
• JSON Schema: frontmatter.schema.json