Sederhanakan Tumpukan Anda Dengan Generator Situs Statis yang Dibuat Khusus

Diterbitkan: 2022-03-10

Ringkasan cepat Dalam perkembangan modern, ada begitu banyak alat hebat untuk mengembangkan situs web, tetapi seringkali alat itu lebih dari yang diperlukan untuk proyek tertentu. Dalam artikel ini, kita akan menjelajahi cara mengambil halaman HTML sederhana dan membuat kontennya dapat diedit dalam CMS tanpa kerangka kerja dan tanpa JavaScript sisi klien.

Dengan munculnya gerakan Jamstack, situs yang dilayani secara statis menjadi populer lagi. Sebagian besar pengembang yang menyajikan HTML statis tidak membuat HTML asli. Untuk memiliki pengalaman pengembang yang solid, kami sering beralih ke alat yang disebut Generator Situs Statis (SSG).

Alat-alat ini hadir dengan banyak fitur yang membuat pembuatan situs statis berskala besar menjadi menyenangkan. Apakah mereka menyediakan pengait sederhana ke API pihak ketiga seperti sumber data Gatsby atau menyediakan konfigurasi mendalam seperti koleksi besar mesin template 11ty, selalu ada sesuatu untuk semua orang dalam pembuatan situs statis.

Karena alat ini dibuat untuk kasus penggunaan yang beragam, alat ini harus memiliki banyak fitur. Fitur-fitur itu membuat mereka kuat. Mereka juga membuatnya cukup rumit dan buram untuk pengembang baru. Pada artikel ini, kita akan membawa SSG ke komponen dasarnya dan membuatnya sendiri.

Apa Itu Generator Situs Statis?

Pada intinya, generator situs statis adalah program yang melakukan serangkaian transformasi pada sekelompok file untuk mengubahnya menjadi aset statis, seperti HTML. Jenis file apa yang dapat diterima, bagaimana mengubahnya, dan jenis file apa yang membedakan SSG.

Jekyll, SSG awal dan masih populer, menggunakan Ruby untuk memproses template Liquid dan file konten penurunan harga menjadi HTML.

Gatsby menggunakan React dan JSX untuk mengubah komponen dan konten menjadi HTML. Kemudian melangkah lebih jauh dan membuat aplikasi satu halaman yang dapat disajikan secara statis.

11ty merender HTML dari mesin templating seperti Liquid, Handlebars, Nunjucks, atau literal templat JavaScript.

Masing-masing platform ini memiliki fitur tambahan untuk membuat hidup kita lebih mudah. Mereka menyediakan tema, membangun saluran pipa, arsitektur plugin, dan banyak lagi. Dengan setiap fitur tambahan, muncul lebih banyak kerumitan, lebih banyak keajaiban, dan lebih banyak ketergantungan. Itu adalah fitur penting, tentu saja, tetapi tidak setiap proyek membutuhkannya.

Di antara ketiga SSG yang berbeda ini, kita dapat melihat tema umum lainnya: data + template = situs akhir. Ini tampaknya menjadi fungsi inti dari situs statis generator. Ini adalah fungsi yang akan kami gunakan untuk SSG kami.

Pada intinya, generator situs statis adalah program yang melakukan serangkaian transformasi pada sekelompok file untuk mengubahnya menjadi aset statis, seperti HTML.
“

Tumpukan Teknologi Generator Situs Statis Baru Kami: Setang, Sanity.io, dan Netlify

Untuk membangun SSG kami, kami memerlukan mesin template, sumber data, dan host yang dapat menjalankan SSG kami dan membangun situs kami. Banyak generator menggunakan penurunan harga sebagai sumber data, tetapi bagaimana jika kita melangkah lebih jauh dan menghubungkan SSG kita ke CMS secara native?

Sumber Data: Sanity.io
Pengambilan dan pembuatan template data: Node dan Handlebars
Host dan Penerapan: Netlify.

Prasyarat

NodeJS diinstal
akun Sanity.io
Pengetahuan tentang Git
Pengetahuan dasar tentang baris perintah
Pengetahuan dasar penerapan ke layanan seperti Netlify.

Catatan : Untuk mengikuti, Anda dapat menemukan kode di repositori ini di GitHub.

Lebih banyak setelah melompat! Lanjutkan membaca di bawah ini

Menyiapkan Struktur Dokumen Kami Dalam HTML

Untuk memulai struktur dokumen kita, kita akan menulis HTML biasa. Tidak perlu memperumit masalah lagi.

Dalam struktur proyek kami, kami perlu membuat tempat untuk file sumber kami untuk hidup. Dalam hal ini, kita akan membuat direktori src dan meletakkan index.html kita di dalamnya.

Di index.html , kami akan menguraikan konten yang kami inginkan. Ini akan menjadi halaman about yang relatif sederhana.

 <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Title of the page!</title> </head> <body> <h1>The personal homepage of Bryan Robinson</h1> <p>Some pagraph and rich text content next</p> <h2>Bryan is on the internet</h2> <ul> <li><a href="linkURL">List of links</a></li> </ul> </body> </html>

Mari kita tetap sederhana. Kita akan mulai dengan h1 untuk halaman kita. Kami akan mengikutinya dengan beberapa paragraf informasi biografi, dan kami akan mengaitkan halaman dengan daftar tautan untuk melihat lebih banyak.

Ubah HTML Kami Menjadi Template yang Menerima Data

Setelah kita memiliki struktur dasar, kita perlu menyiapkan proses untuk menggabungkan ini dengan sejumlah data. Untuk melakukan ini, kita akan menggunakan mesin template Handlebars.

Pada intinya, Handlebars mengambil string seperti HTML, memasukkan data melalui aturan yang ditentukan dalam dokumen, dan kemudian mengeluarkan string HTML yang dikompilasi.

Untuk menggunakan Handlebars, kita perlu menginisialisasi package.json dan menginstal paket.

Jalankan npm init -y untuk membuat struktur file package.json dengan beberapa konten default. Setelah kita memiliki ini, kita dapat menginstal Handlebars.

 npm install handlebars

Skrip build kami akan menjadi skrip Node. Ini adalah skrip yang akan kami gunakan secara lokal untuk membangun, tetapi juga yang akan digunakan oleh vendor dan host penerapan kami untuk membuat HTML kami untuk situs langsung.

Untuk memulai skrip, kita akan membuat file index.js dan membutuhkan dua paket di bagian atas. Yang pertama adalah Handlebars dan yang kedua adalah modul default di Node untuk mengakses sistem file saat ini.

 const fs = require('fs'); const Handlebars = require('handlebars');

Kami akan menggunakan modul fs untuk mengakses file sumber kami, serta untuk menulis ke file distribusi. Untuk memulai build kami, kami akan membuat fungsi main untuk file kami untuk dijalankan saat dipanggil dan fungsi buildHTML untuk menggabungkan data dan markup kami.

 function buildHTML(filename, data) { const source = fs.readFileSync(filename,'utf8').toString(); const template = Handlebars.compile(source); const output = template(data); return output } async function main(src, dist) { const html = buildHTML(src, { "variableData": "This is variable data"}); fs.writeFile(destination, html, function (err) { if (err) return console.log(err); console.log('index.html created'); }); } main('./src/index.html', './dist/index.html');

Fungsi main() menerima dua argumen: jalur ke template HTML kita dan jalur yang kita inginkan untuk menjalankan file yang kita buat. Dalam fungsi utama kami, kami menjalankan buildHTML pada jalur sumber template dengan sejumlah data.

Fungsi build mengonversi dokumen sumber menjadi string dan meneruskan string tersebut ke Handlebars. Handlebars mengkompilasi template menggunakan string itu. Kami kemudian meneruskan data kami ke dalam template yang dikompilasi, dan Handlebars membuat string HTML baru menggantikan variabel atau logika template dengan output data.

Kami mengembalikan string itu ke fungsi main kami dan menggunakan metode writeFile yang disediakan oleh modul sistem file Node untuk menulis file baru di lokasi yang kami tentukan jika direktori ada.

Untuk mencegah kesalahan, tambahkan direktori dist ke proyek Anda dengan file .gitkeep di dalamnya. Kami tidak ingin mengkomit file yang kami buat (proses pembuatan kami akan melakukan ini), tetapi kami ingin memastikan untuk memiliki direktori ini untuk skrip kami.

Sebelum kita membuat CMS untuk mengelola halaman ini, mari kita pastikan itu berfungsi. Untuk menguji, kami akan memodifikasi dokumen HTML kami untuk menggunakan data yang baru saja kami berikan ke dalamnya. Kami akan menggunakan sintaks variabel Handlebars untuk memasukkan konten variableData .

 <h1>{{ variableData }}</h1>

Sekarang HTML kami memiliki variabel, kami siap untuk menjalankan skrip simpul kami.

 node index.js

Setelah skrip selesai, kita harus memiliki file di /dist/index.html . Jika kita membaca open this di browser, kita akan melihat markup kita dirender, tetapi juga string "This is variable data" kita.

Menghubungkan ke CMS

Kami memiliki cara untuk menyatukan data dengan template, sekarang kami membutuhkan sumber untuk data kami. Metode ini akan bekerja dengan sumber data apa pun yang memiliki API. Untuk demo ini, kami akan menggunakan Sanity.io.

Sanity adalah sumber data pertama API yang memperlakukan konten sebagai data terstruktur. Mereka memiliki sistem manajemen konten sumber terbuka untuk membuat pengelolaan dan penambahan data lebih nyaman bagi editor dan pengembang. CMS inilah yang sering disebut sebagai CMS "Tanpa Kepala". Alih-alih sistem manajemen tradisional di mana data Anda digabungkan dengan erat ke presentasi Anda, CMS tanpa kepala membuat lapisan data yang dapat digunakan oleh frontend atau layanan apa pun (dan mungkin banyak pada saat yang sama).

Sanity adalah layanan berbayar, tetapi mereka memiliki paket "Standar" yang gratis dan memiliki semua fitur yang kami butuhkan untuk situs seperti ini.

Menyiapkan Kewarasan

Cara tercepat untuk memulai dan menjalankan proyek Sanity baru adalah dengan menggunakan CLI Sanity. Kita akan mulai dengan menginstalnya secara global.

 npm install -g @sanity/cli

CLI memberi kami akses ke sekelompok pembantu untuk mengelola, menerapkan, dan membuat. Untuk memulai, kita akan menjalankan sanity init . Ini akan memandu kami melalui kuesioner untuk membantu bootstrap Studio kami (apa yang disebut Sanity sebagai CMS open-source mereka).

 Select a Project to Use: Create new project HTML CMS Use the default dataset configuration? Y // this creates a "Production" dataset Project output path: studio // or whatever directory you'd like this to live in Select project template Clean project with no predefined schemas

Langkah ini akan membuat proyek dan kumpulan data baru di akun Sanity Anda, membuat versi lokal Studio, dan menyatukan data dan CMS untuk Anda. Secara default, direktori studio akan dibuat di root proyek kami. Dalam proyek skala besar, Anda mungkin ingin mengatur ini sebagai repositori terpisah. Untuk proyek ini, tidak apa-apa untuk tetap mengikatnya.

Untuk menjalankan Studio kami secara lokal, kami akan mengubah direktori menjadi direktori studio dan menjalankan sanity start . Ini akan menjalankan Studio di localhost:3333 . Saat Anda masuk, Anda akan disajikan dengan layar untuk memberi tahu Anda bahwa Anda memiliki "Skema kosong." Dengan itu, saatnya untuk menambahkan skema kita, yaitu bagaimana data kita akan terstruktur dan diedit.

Membuat Skema Kewarasan

Cara Anda membuat dokumen dan bidang di dalam Sanity Studio adalah dengan membuat skema di dalam file schemas/schema.js .

Untuk situs kami, kami akan membuat jenis skema yang disebut "Tentang Detail." Skema kami akan mengalir dari HTML kami. Secara umum, kami dapat membuat sebagian besar halaman web kami menjadi satu bidang teks kaya, tetapi ini adalah praktik terbaik untuk menyusun konten kami dengan cara yang terpisah. Ini memberikan fleksibilitas yang lebih besar dalam cara kami mungkin ingin menggunakan data ini di masa mendatang.

Untuk halaman web kami, kami menginginkan satu set data yang mencakup berikut ini:

Judul
Nama lengkap
Biografi (dengan pengeditan teks kaya)
Daftar situs web dengan nama dan URL.

Untuk mendefinisikan ini dalam skema kami, kami membuat objek untuk dokumen kami dan menentukan bidangnya. Daftar beranotasi dari konten kami dengan type bidangnya:

Judul — string
Nama Lengkap — string
Biografi — susunan “blok”
Daftar situs web — larik objek dengan bidang string nama dan URL.

 types: schemaTypes.concat([ /* Your types here! */ { title: "About Details", name: "about", type: "document", fields: [ { name: 'title', type: 'string' }, { name: 'fullName', title: 'Full Name', type: 'string' }, { name: 'bio', title: 'Biography', name: 'content', type: 'array', of: [ { type: 'block' } ] }, { name: 'externalLinks', title: 'Social media and external links', type: 'array', of: [ { type: 'object', fields: [ { name: 'text', title: 'Link text', type: 'string' }, { name: 'href', title: 'Link url', type: 'string' } ] } ] } ] } ])

Tambahkan ini ke jenis skema Anda, simpan dan Studio Anda akan mengkompilasi ulang dan memberi Anda dokumen pertama Anda. Dari sini, kami akan menambahkan konten kami ke dalam CMS dengan membuat dokumen baru dan mengisi informasi.

Menyusun Konten Anda Dengan Cara yang Dapat Digunakan Kembali

Pada titik ini, Anda mungkin bertanya-tanya mengapa kami memiliki "nama lengkap" dan "gelar". Ini karena kami ingin konten kami berpotensi multiguna. Dengan menyertakan bidang nama alih-alih memasukkan nama hanya di judul, kami memberikan lebih banyak penggunaan data itu. Kami kemudian dapat menggunakan informasi dalam CMS ini untuk juga memberi daya pada halaman resume atau PDF. Bidang biografi dapat digunakan secara terprogram di sistem atau situs web lain. Ini memungkinkan kami untuk memiliki satu sumber kebenaran untuk sebagian besar konten ini alih-alih didikte oleh kasus penggunaan langsung dari situs khusus ini.

Menarik Data Kami Ke Proyek Kami

Sekarang kita telah membuat data kita tersedia melalui API, mari kita tarik ke dalam proyek kita.

Instal dan konfigurasikan klien Sanity JavaScript

Hal pertama, kita memerlukan akses ke data di Node.js. Kita dapat menggunakan klien Sanity JavaScript untuk menjalin koneksi itu.

 npm install @sanity/client

Ini akan mengambil dan menginstal SDK JavaScript. Dari sini, kita perlu mengonfigurasinya untuk mengambil data dari proyek yang kita siapkan sebelumnya. Untuk melakukannya, kita akan menyiapkan skrip utilitas di /utils/SanityClient.js . Kami menyediakan SDK dengan ID proyek dan nama set data kami, dan kami siap menggunakannya dalam skrip utama kami.

 const sanityClient = require('@sanity/client'); const client = sanityClient({ projectId: '4fs6x5jg', dataset: 'production', useCdn: true }) module.exports = client;

Mengambil Data Kami Dengan GROQ

Kembali ke file index.js , kita akan membuat fungsi baru untuk mengambil data kita. Untuk melakukan ini, kami akan menggunakan bahasa kueri asli Sanity, GROQ open-source.

Kami akan membuat kueri dalam variabel dan kemudian menggunakan klien yang kami konfigurasikan untuk mengambil data berdasarkan kueri. Dalam hal ini, kita membangun sebuah objek dengan properti bernama about . Dalam objek ini, kami ingin mengembalikan data untuk dokumen khusus kami. Untuk melakukan itu, kami membuat kueri berdasarkan dokumen _id yang dihasilkan secara otomatis saat kami membuat dokumen kami.

Untuk menemukan _id dokumen, kami menavigasi ke dokumen di Studio dan menyalinnya dari URL atau pindah ke mode "Periksa" untuk melihat semua data pada dokumen. Untuk masuk ke Inspect, klik menu “kabob” di kanan atas atau gunakan shortcut Ctrl + Alt + I . Tampilan ini akan mencantumkan semua data pada dokumen ini, termasuk _id kami. Sanity akan mengembalikan array objek dokumen, jadi demi kesederhanaan, kami akan mengembalikan entri ke- 0th .

Kami kemudian meneruskan kueri ke metode fetch klien Sanity kami dan itu akan mengembalikan objek JSON dari semua data dalam dokumen kami. Dalam demo ini, mengembalikan semua data bukanlah masalah besar. Untuk implementasi yang lebih besar, GROQ memungkinkan "proyeksi" opsional untuk hanya mengembalikan bidang eksplisit yang Anda inginkan.

 const client = require('./utils/SanityClient') // at the top of the file // ... async function getSanityData() { const query = `{ "about": *[_id == 'YOUR-ID-HERE'][0] }` let data = await client.fetch(query); }

Mengubah Bidang Teks Kaya Menjadi HTML

Sebelum kita dapat mengembalikan data, kita perlu melakukan transformasi pada bidang rich text kita. Sementara banyak CMS menggunakan editor teks kaya yang mengembalikan HTML secara langsung, Sanity menggunakan spesifikasi sumber terbuka yang disebut Teks Portabel. Teks Portabel mengembalikan larik objek (anggap teks kaya sebagai daftar paragraf dan blok media lainnya) dengan semua data tentang gaya teks kaya dan properti seperti tautan, catatan kaki, dan anotasi lainnya. Ini memungkinkan teks Anda dipindahkan dan digunakan dalam sistem yang tidak mendukung HTML, seperti asisten suara dan aplikasi asli.

Untuk kasus penggunaan kami, itu berarti kami perlu mengubah objek menjadi HTML. Ada modul NPM yang dapat digunakan untuk mengubah teks portabel menjadi berbagai kegunaan. Dalam kasus kami, kami akan menggunakan paket yang disebut block-content-to-html.

 npm install @sanity/block-content-to-html

Paket ini akan membuat semua markup default dari editor teks kaya. Setiap jenis gaya dapat diganti agar sesuai dengan markup apa pun yang Anda butuhkan untuk kasus penggunaan Anda. Dalam hal ini, kami akan membiarkan paket yang bekerja untuk kami.

 const blocksToHtml = require('@sanity/block-content-to-html'); // Added to the top async function getSanityData() { const query = `{ "about": *[_type == 'about'][0] }` let data = await client.fetch(query); data.about.content = blocksToHtml({ blocks: data.about.content }) return await data }

Menggunakan Konten Dari Sanity.io Di Setang

Sekarang setelah data dalam bentuk yang dapat kita gunakan, kita akan meneruskan ini ke fungsi buildHTML sebagai argumen data.

 async function main(src, dist) { const data = await getSanityData(); const html = buildHTML(src, data) fs.writeFile(dist, html, function (err) { if (err) return console.log(err); console.log('index.html created'); }); }

Sekarang, kita dapat mengubah HTML kita untuk menggunakan data baru. Kami akan menggunakan lebih banyak panggilan variabel di template kami untuk menarik sebagian besar data kami.

Untuk merender variabel content teks kaya kita, kita perlu menambahkan lapisan kurung kurawal tambahan ke variabel kita. Ini akan memberi tahu Handlebars untuk merender HTML alih-alih menampilkan HTML sebagai string.

Untuk array externalLinks kami, kami harus menggunakan fungsi looping bawaan Handlebars untuk menampilkan semua tautan yang kami tambahkan ke Studio kami.

 <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>{{ about.title }}</title> </head> <body> <h1>The personal homepage of {{ about.fullName }}</h1> {{{ about.content }}} <h2>Bryan is on the internet</h2> <ul> {{#each about.externalLinks }} <li><a href="{{ this.href }}">{{ this.text }}</a></li> {{/each}} </ul> </body> </html>

Menyiapkan Penerapan

Mari kita hidupkan ini. Kita membutuhkan dua komponen untuk membuat ini bekerja. Pertama, kami menginginkan host statis yang akan membangun file kami untuk kami. Selanjutnya, kita perlu memicu pembuatan baru situs kita saat konten diubah di CMS kita.

Menyebarkan ke Netlify

Untuk hosting, kami akan menggunakan Netlify. Netlify adalah host situs statis. Ini melayani aset statis, tetapi memiliki fitur tambahan yang akan membuat situs kami bekerja dengan lancar. Mereka memiliki infrastruktur penerapan bawaan yang dapat menjalankan skrip simpul kami, webhook untuk memicu pembuatan, dan CDN yang didistribusikan secara global untuk memastikan laman HTML kami disajikan dengan cepat.

Netlify dapat melihat repositori kami di GitHub dan membuat build berdasarkan perintah yang dapat kami tambahkan di dasbor mereka.

Pertama, kita perlu memasukkan kode ini ke GitHub. Kemudian, di Dasbor Netlify, kita perlu menghubungkan repositori baru ke situs baru di Netlify.

Setelah terhubung, kita perlu memberi tahu Netlify bagaimana membangun proyek kita. Di dasbor, kita akan menuju ke Settings > Build & Deploy > Build Settings. Di area ini, kita perlu mengubah "Build command" menjadi "node index.js" dan "Publish directory" menjadi "./dist".

Ketika Netlify membangun situs kami, itu akan menjalankan perintah kami dan kemudian memeriksa folder yang kami daftarkan untuk konten dan mempublikasikan konten di dalamnya.

Menyiapkan Webhook

Kami juga perlu memberi tahu Netlify untuk menerbitkan versi baru ketika seseorang memperbarui konten. Untuk melakukannya, kami akan menyiapkan Webhook untuk memberi tahu Netlify bahwa kami memerlukan situs untuk dibangun kembali. Webhook adalah URL yang dapat diakses secara terprogram oleh layanan yang berbeda (seperti Sanity) untuk membuat tindakan di layanan asal (dalam hal ini Netlify).

Kami dapat mengatur "Build hook" tertentu di dasbor Netlify kami di Settings > Build & Deploy > Build hooks. Tambahkan kail, beri nama dan simpan. Ini akan memberikan URL yang dapat digunakan untuk memicu build di Netlify dari jarak jauh.

Selanjutnya, kami perlu memberi tahu Sanity untuk membuat permintaan ke URL ini saat Anda memublikasikan perubahan.

Kita dapat menggunakan Sanity CLI untuk mencapai ini. Di dalam direktori /studio kami, kami dapat menjalankan sanity hook create untuk terhubung. Perintah akan menanyakan nama, kumpulan data, dan URL. Nama dapat berupa apa pun yang Anda inginkan, kumpulan data harus production untuk produk kami, dan URL harus berupa URL yang disediakan Netlify.

Sekarang, setiap kali kami mempublikasikan konten di Studio, situs web kami akan diperbarui secara otomatis. Tidak ada kerangka kerja yang diperlukan.

Kode dapat ditemukan di repositori GitHub ini →

Langkah selanjutnya

Ini adalah contoh kecil dari apa yang dapat Anda lakukan saat membuat perkakas sendiri. Meskipun SSG berfitur lengkap mungkin yang Anda perlukan untuk sebagian besar proyek, membuat SSG mini sendiri dapat membantu Anda memahami lebih lanjut tentang apa yang terjadi di generator pilihan Anda.

Situs ini hanya menerbitkan satu halaman, tetapi dengan sedikit tambahan dalam skrip build kami, kami dapat membuatnya menerbitkan lebih banyak halaman. Bahkan bisa mempublikasikan posting blog.
"Pengalaman pengembang" sedikit kurang dalam repositori. Kami dapat menjalankan skrip Node kami pada penyimpanan file apa pun dengan menerapkan paket seperti Nodemon atau menambahkan "hot reload" dengan sesuatu seperti BrowserSync.
Data yang ada di Sanity dapat memberi daya pada banyak situs dan layanan. Anda dapat membuat situs resume yang menggunakan ini dan menerbitkan PDF alih-alih halaman web.
Anda dapat menambahkan CSS dan membuatnya terlihat seperti situs nyata.