Pemasangan dan Konfigurasi Jigsaw dalam Persekitaran ServBay

Pengenalan

Dokumen ini bertujuan membimbing anda tentang cara memasang dan mengkonfigurasi pembangun laman web statik Jigsaw dalam persekitaran pembangunan Web tempatan ServBay yang berkuasa. ServBay menyediakan persekitaran bersepadu untuk pelbagai stack teknologi seperti PHP dan Node.js, seterusnya memudahkan proses penubuhan projek Jigsaw. Dengan ServBay, anda boleh mengkonfigurasi domain tempatan, HTTPS, dan pelayan web cekap untuk projek Jigsaw anda dengan mudah, membolehkan anda fokus pada pembangunan kandungan laman web.

Apa Itu Jigsaw?

Jigsaw ialah pembangun laman web statik berasaskan komponen Laravel, dibangunkan oleh Tighten. Ia memanfaatkan kehebatan serta fleksibiliti enjin template Laravel Blade dan menggabungkannya dengan fail Markdown untuk menjana laman HTML statik sepenuhnya. Jigsaw sangat sesuai untuk membina laman dokumentasi, blog, halaman pemasaran atau mana-mana laman yang tidak memerlukan pangkalan data backend dan pemprosesan pelayan dinamik. Antara kelebihan utamanya ialah:

• Guna alat yang anda sudah biasa: Jika anda pernah menggunakan Laravel atau Blade template, Jigsaw sangat mudah dipelajari.
• Prestasi dan keselamatan: Laman statik sangat pantas untuk dimuat dan lebih selamat kerana tiada kod pelayan yang berjalan.
• Template fleksibel: Template Blade membolehkan anda mencipta susun atur dan komponen kompleks.
• Sokongan Markdown: Penulisan kandungan sangat mudah.

Senario Penggunaan

Jigsaw sesuai untuk:

• Laman dokumentasi projek atau API
• Blog peribadi atau laman perkongsian teknologi
• Halaman pendaratan pemasaran untuk syarikat/produk
• Laman portfolio berskala kecil
• Mana-mana laman dengan kandungan tetap yang memerlukan prestasi dan keselamatan tinggi

Prasyarat

Sebelum bermula, pastikan anda memenuhi syarat berikut:

1. ServBay telah dipasang dan berjalan: Anda memerlukan ServBay yang telah dipasang dan dihidupkan pada sistem macOS anda. ServBay didatangkan dengan PHP, Composer dan Node.js/npm yang diperlukan untuk pemasangan dan operasi Jigsaw.
2. Pengetahuan asas penggunaan terminal: Anda perlu boleh menjalankan beberapa perintah melalui terminal.
3. Pemahaman asas Composer dan npm: Pemasangan Jigsaw bergantung pada Composer, sementara kompilasi aset frontend menggunakan npm.

Langkah Pemasangan dan Konfigurasi

Bahagian ini menghuraikan langkah demi langkah pemasangan dan konfigurasi projek Jigsaw dalam persekitaran ServBay.

Langkah 1: Cipta Direktori Projek

Mula-mula, buka aplikasi terminal dan navigasi ke direktori root laman web yang disarankan oleh ServBay /Applications/ServBay/www, kemudian cipta satu sub-direktori baharu untuk projek Jigsaw anda.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Kita namakan direktori projek sebagai servbay-jigsaw-demo. Semua fail projek akan disimpan di sini.

Langkah 2: Cipta Projek Jigsaw menggunakan Composer

ServBay telah siap dipasang dan dikonfigurasi dengan Composer, jadi anda boleh menggunakan composer di mana-mana tetingkap terminal. Kini, dalam direktori projek yang anda cipta (/Applications/ServBay/www/servbay-jigsaw-demo), jalankan perintah Composer berikut untuk mencipta projek Jigsaw:

composer create-project tightenco/jigsaw .

Perintah ini akan memuat turun versi terkini Jigsaw berserta semua kebergantungan PHP ke dalam direktori semasa (.). Nota: tanda titik . pada akhir memastikan projek dicipta dalam direktori semasa, bukannya dalam sub-direktori jigsaw.

Langkah 3: Konfigurasi Laman ServBay

Agar anda boleh mengakses laman Jigsaw anda melalui pelayar web, anda perlu mengkonfigurasi satu laman baharu dalam ServBay untuk projek ini.

1. Buka UI ServBay: Klik dua kali ikon aplikasi ServBay atau lancar daripada bar menu untuk membuka panel kawalan ServBay.
2. Navigasi ke “Laman Web”: Pada bar navigasi kiri, klik tab “Laman Web”.
3. Tambah Laman Baru: Klik butang "+" di bawah interface dan pilih “Tambah Laman”.
4. Konfigurasi Butiran Laman:
   • Nama: Masukkan nama mudah dikenali, misalnya ServBay Jigsaw Demo.
   • Domain: Isikan domain untuk akses tempatan. Disarankan guna akhiran .servbay.demo supaya tidak bertembung dengan domain sebenar, sebagai contoh jigsaw-demo.servbay.demo. ServBay akan meleraikan domain .servbay.demo ke alamat tempatan.
   • Jenis Laman: Pilih PHP, kerana proses binaan Jigsaw memerlukan persekitaran PHP.
   • Versi PHP: Pilih mana-mana versi PHP yang dipasang dalam ServBay, versi stabil terkini sangat disarankan.
   • Root Laman Web: Ini langkah penting. Hasil binaan Jigsaw secara lalai diletakkan dalam direktori build_local di root projek. Jadi, tetapkan root laman ke direktori output ini: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Simpan dan Gunakan: Selepas melengkapkan maklumat, klik butang “Simpan”. ServBay akan meminta pengesahan untuk mengaplikasikan perubahan, klik sahkan. ServBay akan mengemaskini konfigurasi pelayan Web (Caddy atau Nginx) dan sediakan HTTPS untuk domain anda.

Langkah 4: Pasang Kebergantungan Frontend

Projek Jigsaw selalunya memerlukan npm bagi mengurus dan kompilasi aset frontend (seperti SASS, fail JavaScript, dan lain-lain). Dalam persekitaran ServBay, Node.js dan npm telah sedia ada.

Jalankan perintah dalam direktori projek (/Applications/ServBay/www/servbay-jigsaw-demo) untuk memasang kebergantungan frontend:

npm install

Arahan ini akan membaca fail package.json di root projek dan memuat turun modul Node.js yang diperlukan ke direktori node_modules.

Langkah 5: Bina Laman Jigsaw

Selepas semua kebergantungan dipasang, jalankan perintah bina Jigsaw untuk menjana fail laman web statik.

Di dalam direktori projek, jalankan:

./vendor/bin/jigsaw build

Perintah ini akan melakukan:

1. Memproses fail Markdown dan template Blade dalam direktori source.
2. Melaksanakan tugas kompilasi yang ditakrif dalam webpack.mix.js (sekiranya penggunaan Laravel Mix didayakan).
3. Meletakkan fail akhir HTML, CSS, JS dan aset lain ke direktori build_local.

Langkah 6: Akses Laman

Kini fail statik laman Jigsaw anda telah dijana dan terletak dalam /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Memandangkan root laman dalam ServBay telah ditetapkan ke sini, anda kini boleh melayari laman ini melalui browser dengan domain tempatan yang telah dikonfigurasi.

Buka pelayar web dan lawati domain yang anda tetapkan pada Langkah 3, contohnya https://jigsaw-demo.servbay.demo. ServBay akan menguruskan sijil HTTPS secara automatik (menggunakan ServBay User CA). Anda sepatutnya melihat halaman selamat datang Jigsaw secara lalai.

Kustomasi dan Pembangunan

Selepas persekitaran asas berjaya disediakan, anda boleh mula mengubah suai kandungan dan gaya laman web Jigsaw anda.

Edit Kandungan dan Template

• Kod sumber laman web berada dalam direktori source di root projek.
• Susun atur HTML dan komponen menggunakan template Blade dan disimpan dalam subdirektori seperti source/_layouts dan source/_partials.
• Kandungan halaman biasanya ditulis dalam format Markdown, terletak di dalam direktori source atau subdirektorinya (seperti source/index.md, source/about.md).
• Artikel blog biasanya diletakkan dalam source/_posts dan dinamakan mengikut format YYYY-MM-DD-slug.md.

Tambah Halaman/Artikel Baru

Untuk menambah halaman atau entri blog baharu, hanya perlu cipta fail Markdown dalam direktori source atau subdirektorinya (seperti source/_posts).

Contoh, cipta fail source/about.md:

---
title: "Tentang Kami"
description: "Ketahui lebih lanjut mengenai ServBay Jigsaw Demo"
---

# Tentang Kami

Ini ialah halaman tentang yang dibina menggunakan Jigsaw.

Di sini anda boleh menambah maklumat syarikat, pasukan, dan sebagainya.

Kustomasi Gaya dan Skrip

Projek Jigsaw biasanya menggunakan Laravel Mix (webpack.mix.js) untuk kompilasi aset frontend.

• Fail gaya (selalunya SASS/SCSS) terletak di source/_assets/sass.
• JavaScript disimpan di dalam source/_assets/js.

Di root projek, anda boleh gunakan skrip npm untuk membina aset:

• npm run dev: Membina aset untuk pembangunan dengan Source Maps, tanpa compress.
• npm run watch: Membina aset pembangunan dan memantau perubahan fail untuk auto-compile. Sesuai semasa proses pembangunan.
• npm run prod: Membina aset siap untuk produksi, dengan compress dan pengoptimuman.

Contohnya, selepas mengubah fail source/_assets/sass/main.scss, jalankan npm run dev atau npm run watch untuk membina semula fail CSS yang berkaitan.

Bina Semula Laman

Penting: Setiap kali anda mengubah fail kandungan (Markdown) atau template (Blade) dalam direktori source, anda perlu menjalankan semula perintah bina Jigsaw supaya perubahan diproses dan fail statik dalam direktori build_local dikemaskini:

./vendor/bin/jigsaw build

Jika anda mengubah fail aset frontend (SASS, JS), jalankan npm run dev atau npm run watch untuk membina aset tersebut. Dalam kebanyakan projek Jigsaw, perintah build Jigsaw juga akan memicu proses kompilasi Mix, tetapi memahami pemisahan ini membantu proses debugging.

Perkara Penting

• Direktori Output Binaan: Secara lalai, Jigsaw membina output ke build_local (pembangunan) dan build_production (produksi). Pastikan root laman ServBay anda menunjuk ke direktori yang diingini (untuk pembangunan biasanya build_local).
• Pelayan Web: ServBay menggunakan Caddy atau Nginx yang terus menyajikan fail dari build_local, memastikan prestasi sangat tinggi. Anda tidak perlu menggunakan perintah jigsaw serve terbina dalam Jigsaw (perintah ini hanya untuk pratinjau pantas dan tidak secanggih pelayan penuh ServBay).
• HTTPS: ServBay akan secara automatik mengkonfigurasi HTTPS untuk domain .servbay.demo dan menggunakan sijil yang dikeluarkan oleh ServBay User CA. Anda mungkin perlu mempercayai sijil ServBay User CA dalam sistem supaya tiada amaran di browser.
• Binaan Bersih: Jika menghadapi masalah pembinaan pelik, cuba jalankan perintah berikut untuk binaan bersih: ./vendor/bin/jigsaw build --clean.

Soalan Lazim (FAQ)

S: Saya ubah fail Markdown tetapi tidak nampak perubahan di pelayar?

J: Selepas membuat perubahan pada kandungan atau template, anda perlu jalankan perintah ./vendor/bin/jigsaw build dalam terminal untuk bina semula laman.

S: Saya ubah fail SCSS tapi gaya tidak berubah?

J: Setelah mengubah aset frontend, jalankan perintah npm run dev atau npm run watch dalam direktori projek untuk membina semula aset frontend.

S: Domain tempatan yang saya lawat memaparkan 'tidak dapat diakses' atau 'file tidak dijumpai'?

J: Sila semak perkara berikut:

1. Pastikan ServBay sedang berjalan.
2. Semak konfigurasi laman di ServBay: adakah domain dan root laman sudah betul menunjuk ke /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Pastikan anda sudah menjalankan ./vendor/bin/jigsaw build dan fail statik (seperti index.html) memang wujud dalam direktori build_local.

S: Bagaimana untuk deploy laman Jigsaw?

J: Fail yang dijana oleh Jigsaw adalah statik sepenuhnya. Proses biasa:

1. Jalankan ./vendor/bin/jigsaw build production untuk membina fail produksi (biasanya akan ada lebih banyak pengoptimuman).
2. Muat naik semua fail dari direktori build_production ke mana-mana penyedia hosting laman statik (contohnya Netlify, Vercel, GitHub Pages, penyimpanan awan dan lain-lain).

Rumusan

Dengan ServBay, pemasangan dan konfigurasi pembangun laman web statik Jigsaw di persekitaran macOS menjadi efisien serta mudah. ServBay menyediakan semua keperluan asas (PHP, Composer, Node.js, npm) dan kebolehan konfigurasi pelayan Web tempatan yang mantap. Dengan mengikuti panduan ini, anda boleh melancarkan projek Jigsaw dengan cepat serta memanfaatkan sepenuhnya kelebihan ServBay untuk mengoptimumkan aliran kerja pembangunan tempatan anda.