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

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

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.