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

docs(adr): ADR-0007: Progressive Enhancement as Baseline Requirement

Aperta
  • Qualcosa non va?
#15 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-0007: Progressive Enhancement as Baseline Requirement

Status

Accepted

Context

HTMX is often misunderstood as "adding JavaScript to make things dynamic." The opposite is true: HTMX enables server-rendered HTML to be enhanced with dynamic behavior while maintaining full functionality without JavaScript.

For documentation sites, this is critical:

  • Search engine crawlers may not execute JavaScript
  • Users on slow connections benefit from immediate content
  • Accessibility tools work better with semantic HTML
  • Corporate firewalls sometimes strip JavaScript

Decision Drivers

  1. Accessibility - Screen readers and assistive tech need working HTML
  2. SEO - Search engines must index content without JS execution
  3. Resilience - Sites must work when JS fails/blocks/loads slowly
  4. HTMX Philosophy - Enhancement, not replacement

Principle

All mdbook-htmx output MUST function completely without JavaScript.
JavaScript (via HTMX) enhances the experience but never underpins it.

Implementation Requirements

1. All Links Must Be Real Links
<!-- ✅ Correct: Works without JS -->
<a href="/docs/chapter-2" hx-boost="true">Chapter 2</a>

<!-- ❌ Wrong: Requires JS to navigate -->
<button hx-get="/docs/chapter-2">Chapter 2</button>
2. Forms Must Submit Normally
<!-- ✅ Correct: Works without JS -->
<form action="/docs/search" method="GET">
  <input type="search" name="q" hx-get="/docs/search" hx-trigger="input changed delay:300ms">
  <button type="submit">Search</button>
</form>

<!-- ❌ Wrong: No fallback action -->
<input hx-get="/docs/search" hx-trigger="keyup">
3. Full Pages Must Be Complete

The pages/ directory contains fully-rendered HTML documents:

<!DOCTYPE html>
<html>
<head>
  <title>Chapter 2 - My Book</title>
</head>
<body>
  <nav><!-- Full navigation --></nav>
  <main id="content">
    <article><!-- Full content --></article>
  </main>
</body>
</html>

No <noscript> fallbacks needed - the page IS the fallback.

4. Content-First Loading
<!-- ✅ Correct: Content loads, then enhances -->
<body hx-boost="true">
  <!-- All content present in initial HTML -->
</body>

<!-- ❌ Wrong: Content loaded via JS -->
<body>
  <div hx-get="/content" hx-trigger="load"></div>
</body>
5. Lazy Loading Is Progressive

Lazy-loaded sections must show meaningful placeholder content:

<!-- ✅ Correct: Placeholder is usable -->
<section hx-get="/docs/examples" hx-trigger="revealed">
  <p>Examples are loading... <a href="/docs/examples">View examples page</a></p>
</section>

<!-- ❌ Wrong: Empty until JS loads -->
<section hx-get="/docs/examples" hx-trigger="revealed"></section>

Verification Checklist

For every generated page, verify:

  • Page renders complete content with JS disabled
  • All navigation links work without JS
  • Search form submits and returns results without JS
  • Sidebar displays full chapter list without JS
  • No empty containers that require JS to populate
  • No <noscript> tags (they indicate broken baseline)

Testing

# Chrome DevTools: Disable JavaScript
# Settings > Preferences > Debugger > Disable JavaScript

# Or via CLI
curl -s https://docs.example.com/chapter-1 | grep -c "<article>"
# Should return 1 (content present)

Consequences

Positive
  • Works everywhere: slow networks, corporate proxies, screen readers
  • SEO-friendly: crawlers see full content
  • Fast First Contentful Paint: no JS blocking
  • Resilient: partial JS failures don't break navigation
Negative
  • Slightly larger initial HTML (full content vs skeleton)
  • Server must render complete pages, not just fragments
  • Some dynamic features need careful design (e.g., live search needs form fallback)

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.