Situs Dokumentasi dengan Situs

Dokumentasi Waves tidak tersusun dari banyak berkas halaman. Repositori menyimpan satu berkas konfigurasi situs.json dan satu berkas induk docs/index.html. Situs memakai keduanya untuk merangkai partial di docs/_pages/ menjadi satu halaman HTML. situs.json:1-4¹ README.md:8-17²

Konfigurasi situs.json

situs.json hanya berisi dua field, dan keduanya menentukan berkas mana yang ikut diproses. situs.json:1-4¹

Karena _pages masuk daftar ignore, partial di sana tidak pernah menjadi halaman sendiri. Partial hanya muncul di hasil akhir setelah disisipkan ke docs/index.html, dan setiap partial sudah membawa kelas hide pada elemen akarnya sehingga tidak ada bagian yang tampil sebelum JavaScript memunculkannya. docs/_pages/home.html:1-2³

Langkah menjalankan dokumentasi di komputer sendiri ada di README: pasang Situs global dengan npm install situs -g, jalankan grunt atau grunt build, lalu nyalakan situs server dan buka http://localhost:4000/. README.md:12-17⁴

Struktur situs

graph TD berikut menunjukkan bagaimana konfigurasi, partial, dan router bertemu di satu berkas induk.

graph TD
    CFG["situs.json: source ./docs, ignore _pages/**/*"]
    ENTRY["docs/index.html"]
    P1["docs/_pages/home.html"]
    P2["docs/_pages/examples.html"]
    P3["docs/_pages/source.html"]
    P4["docs/_pages/getting-started.html"]
    P5["docs/_pages/api.html"]
    P6["docs/_pages/faq.html"]
    PAGE["satu halaman HTML hasil rakitan"]
    ROUTER["routing(): baca window.location.hash"]
    NAV["#examples #start #api #faq"]
    CFG --> ENTRY
    P1 --> ENTRY
    P2 --> ENTRY
    P3 --> ENTRY
    P4 --> ENTRY
    P5 --> ENTRY
    P6 --> ENTRY
    ENTRY --> PAGE
    PAGE --> ROUTER
    ROUTER --> NAV
    style CFG fill:#f59e0b,color:#000
    style ENTRY fill:#336791,color:#fff
    style PAGE fill:#2d7d46,color:#fff
    style ROUTER fill:#8b5cf6,color:#fff
%% fig: Struktur situs dokumentasi Waves
%% desc: situs.json dan enam partial bertemu di docs/index.html, lalu routing() memilih bagian yang tampil berdasarkan hash.

docs/index.html menyisipkan enam partial dengan direktif @situs-include, masing-masing ditutup titik koma. docs/index.html:50-60⁵

Empat partial memakai kelas section page, #landing hanya memakai section hide, dan #source-code hanya memakai hide. docs/_pages/examples.html:1⁶ docs/_pages/getting-started.html:1⁷ docs/_pages/api.html:1⁸ docs/_pages/faq.html:1⁹

#source-code bukan bagian yang dirutekan lewat hash. Lapisan itu dibuka oleh handler klik #example .top-button dan ditutup oleh handler #source-code .top-button. docs/_pages/source.html:1¹⁰ docs/index.html:222-234¹¹

Peta rute hash

Navigasi di docs/index.html hanya memakai anchor hash tanpa berkas tujuan. docs/index.html:41-46¹²

Objek routes memuat lima kunci itu. Rute index punya transisi sendiri, sedangkan examples, start, api, dan faq memanggil enterTransition dan leaveTransition dengan nama elemen masing-masing. docs/index.html:105-171¹³ docs/index.html:132-159¹⁴

routing() membaca window.location.hash, membuang tanda #, dan menggantinya dengan 'index' bila kosong. Hash di luar daftar ['index', 'examples', 'start', 'api', 'faq'] langsung dijawab return false. docs/index.html:173-197¹⁵ docs/index.html:181-183¹⁶

Percabangan berikutnya memakai currentRoute. Selama currentRoute masih false, hanya enter rute tujuan yang dijalankan. Setelah itu leave rute lama dipanggil lebih dulu, dan enter rute baru dijalankan di dalam callback-nya. docs/index.html:185-195¹⁷

Pemanggilan pertama datang dari init(): setelah jeda 500 ms #navigation mendapat kelas show, lalu routing() dijalankan. Perubahan hash berikutnya ditangani $(window).on('hashchange', routing). docs/index.html:199-204¹⁸ docs/index.html:214-216¹⁹

Landing punya jalur sendiri: enter menghapus hide lalu menambah show setelah 100 ms, sedangkan leave menghapus show dan menambah hide setelah 500 ms, tanpa kelas appear maupun flow. docs/index.html:108-129²⁰

Siklus transisi kelas

enterTransition dan leaveTransition menggerakkan tiga kelas, show, appear, dan flow, dengan jeda bertingkat. docs/index.html:70-103²¹

stateDiagram-v2
    [*] --> hidden
    hidden --> shown: "enter: removeClass hide, addClass show dan appear"
    shown --> flowing: "1000 ms: addClass flow, callback"
    flowing --> shown: "leave: removeClass flow dan show"
    shown --> hidden: "300 ms lalu 500 ms: removeClass appear, addClass hide"
%% fig: Siklus kelas satu bagian
%% desc: Bagian bergerak dari hidden ke shown dan flowing saat masuk, lalu kembali lewat dua jeda saat keluar.

Angka itu berasal dari dua setTimeout bertingkat: 100 ms lalu 1000 ms pada enterTransition, dan 300 ms lalu 500 ms pada leaveTransition. docs/index.html:70-103²¹

Jebakan saat menambah bagian

⚠️ Menambah satu partial baru menuntut tiga suntingan yang sinkron: direktif @situs-include di docs/index.html, kunci baru di objek routes, dan entri baru di daftar putih ['index', 'examples', 'start', 'api', 'faq']. Bila daftar putih terlewat, routing() berhenti di return false dan bagian baru tetap memakai kelas hide sehingga tidak pernah tampil. docs/index.html:50-60⁵ docs/index.html:181-183¹⁶

Nama kunci juga tidak selalu sama dengan id elemen: start mengarah ke #getting-started dan examples mengarah ke #example. Menyalin nama kunci menjadi nama elemen membuat enterTransition mencari elemen yang tidak ada. docs/index.html:132-159¹⁴

Berkas gaya dan skrip halaman ini dimuat dari ./static/: prims.css, snarl.min.css, style.css, serta waves.min.css?v=0.7.6 dan waves.min.js?v=0.7.6. Cara berkas itu sampai ke docs/static/ dibahas di Pipeline Build Grunt dan Artefak Distribusi. docs/index.html:15-19²²