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(adr): ADR-0002: Dual Output Mode (Full Pages + Fragments)

Đang mở
  • Có gì không ổn?
#10 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

ADR-0002: Dual Output Mode (Full Pages + Fragments)

Status

Accepted

Context

HTMX-based applications require two types of responses:

  1. Full page - Initial load or non-HTMX clients (includes <html>, <head>, layout)
  2. Fragment - HTMX requests with HX-Request: true header (content only)

The backend must decide how to generate these outputs.

Decision Drivers

  1. Server Simplicity - Minimize runtime logic in serving layer
  2. Cache Efficiency - Static files can be cached at CDN edge
  3. Flexibility - Support different deployment models
  4. Build Performance - Avoid excessive output duplication

Options Considered

Option A: Single Output, Runtime Detection

Generate only full pages; server strips layout at runtime.

book/htmx/
└── pages/
    └── chapter-1.html   # Full page only

Server uses HTML parsing (lol_html, cheerio) to extract <main> content.

Pros:

  • Smaller build output
  • Single source of truth

Cons:

  • Runtime overhead on every HTMX request
  • Requires HTML parser in server
  • Complex edge caching (Vary header needed)
Option B: Fragment-Only Output

Generate only fragments; server wraps in layout at runtime.

book/htmx/
└── fragments/
    └── chapter-1.html   # Content only

Server composes full pages by injecting fragment into layout.

Pros:

  • Smallest build output
  • DRY templates

Cons:

  • Full page requests require runtime composition
  • Layout changes require server restart
  • Less cacheable
Option C: Dual Output (Recommended)

Generate both full pages and fragments at build time.

book/htmx/
├── pages/
│   └── chapter-1.html      # Full page (layout + content)
└── fragments/
    └── chapter-1.html      # Content only

Server selects file based on HX-Request header.

Pros:

  • Zero runtime overhead (file selection only)
  • Full CDN cacheability
  • Works with static file servers
  • Progressive enhancement (works without JS)

Cons:

  • ~2x output size
  • Build-time layout changes require rebuild
Option D: Configurable Mode

Let user choose via config:

[output.htmx]
output-mode = "full" | "fragments" | "both"

Pros:

  • Maximum flexibility
  • Users optimize for their deployment

Cons:

  • More complex documentation
  • Testing burden

Decision

Implement dual output as default, with configurable output-mode.

Default: output-mode = "both"

Rationale:

  1. Zero runtime overhead is critical for edge deployments (Cloudflare Workers)
  2. Static file selection (HX-Request → fragments/, else → pages/) is trivial
  3. Storage is cheap; compute at edge is not
  4. Progressive enhancement requires full pages for initial load
  5. Config option satisfies users with specific constraints

Implementation

enum OutputMode {
    Full,       // Only pages/
    Fragments,  // Only fragments/
    Both,       // Both directories (default)
}

fn render_chapter(&self, chapter: &Chapter, mode: OutputMode) {
    match mode {
        OutputMode::Full | OutputMode::Both => {
            write_file(pages_dir.join(&chapter.path), render_full(chapter));
        }
        OutputMode::Fragments | OutputMode::Both => {
            write_file(fragments_dir.join(&chapter.path), render_fragment(chapter));
        }
    }
}

Consequences

Positive
  • Simple server logic (file routing only)
  • CDN-friendly (static files, no Vary complexity)
  • Works with any static file server
  • Progressive enhancement out of the box
Negative
  • Larger build output (~2x for both mode)
  • Layout changes require full rebuild
Mitigation
  • Document output-mode = "fragments" for dynamic server deployments
  • Implement incremental builds (only changed chapters)

References

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.