Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

docs(mdbook-htmx): config reference

Đang mở
  • Có gì không ổn?
#32 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

@aRustyDev đang làm issue này rồi.

Từ ngày 5/1/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

documentation

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:

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

[output.htmx]
version = "1.0"
HTMX Version

Controls which HTMX library version is bundled:

[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 
[output.htmx]
swap-strategy = "innerHTML"
Template Engine

Supported template engines:

Value Description
tera Tera (Jinja2-like, default)
handlebars Handlebars
nunjucks Nunjucks
liquid Liquid 
[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) 
[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 
[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 
[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 
[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 
[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 
[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 
[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 
[output.htmx.scopes]
enabled = true
available = ["all", "developers", "managers", "sre"]
default = "all"
global-scopes = ["all"]

Complete Example

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

[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 
MDBOOK_HTMX_MINIFY=true mdbook build

Related Documentation

Ngôn ngữ chính
Rust
Star
0
Fork
1
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của aRustyDev/mdbook-htmx

Tất cả issue của aRustyDev/mdbook-htmx

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.