Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#10 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@aRustyDev ci sta già lavorando.

Dal 5/1/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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

Lingua principale
Rust
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aRustyDev/mdbook-htmx

Tutte le issue di aRustyDev/mdbook-htmx

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.