stacy
v2.0.0
Stacy adalah generator situs web yang menggabungkan konten dari Contentful CMS dengan template Handlebars untuk membuat halaman situs web.
Stacy mencocokkan tipe konten entri Contentful dengan templat Handlebars di proyek situs web Anda dalam hubungan satu lawan satu—ada templat untuk setiap tipe entri yang ditentukan dalam model Konten Anda. Ada dua jenis entri dari sudut pandang Stacy: entri halaman dan entri modul . Entri halaman yang digabungkan dengan templatnya menghasilkan satu halaman situs web dengan URL unik. Entri modul dapat disertakan dalam halaman dan modul lain menggunakan bidang Referensi Contentful untuk membuat konten yang dapat digunakan kembali atau sekadar menyediakan struktur konten dan templat dengan memecahnya menjadi bagian-bagian yang lebih kecil.
Apa yang membuat Stacy berbeda dari banyak generator situs web statis yang ada adalah ia mendukung penerbitan otomatis situs web ke bucket S3 di Amazon Cloud, yang kemudian dapat disajikan di Internet. Stacy menerapkan infrastruktur khusus di Amazon Cloud yang dapat dihubungkan ke Contentful melalui fungsionalitas Webhook-nya. Saat konten diperbarui di ruang Contentful Anda, infrastruktur situs web Anda yang diterapkan oleh Stacy di Amazon Cloud akan diberi tahu dan secara otomatis membuat ulang dan menerbitkan ulang hanya halaman situs web Anda yang terpengaruh oleh pembaruan. Tidak diperlukan regenerasi dan penempatan ulang situs web secara manual.
Saat menggunakan Stacy, situs web Anda adalah proyek NPM yang biasanya diperiksa di repositori git untuk kontrol versi. Proyek ini mencakup templat Setang dan konten statis (seperti lembar gaya CSS, gambar yang digunakan dalam desain situs web, font, dll.), sedangkan konten situs web berada di ruang Contentful. Dari proyek situs web, pengembang situs web menggunakan alat baris perintah Stacy untuk mengembangkan, menerbitkan, dan menerbitkan ulang situs. Setelah situs web dipublikasikan di Amazon Cloud, penulis konten hanya bekerja dengan Contentful UI.
Lihat Membuat Situs Web dengan Stacy untuk tutorial/panduan mendetail.
Pertama, Anda memerlukan ruang Contentful untuk konten situs web Anda. Setelah Anda memilikinya, Anda dapat membuat proyek baru untuk situs web Anda.
Pastikan Anda menginstal Node.js versi 10.16.3 atau lebih baru bersama dengan npm. Jika Anda akan menerbitkan situs web di Amazon Cloud, Anda juga perlu menginstal AWS CLI.
Mulailah dengan menginstal Stacy secara global:
npm install -g stacy
Di ruang Contentful Anda, buka Space settings→API key dan tambahkan kunci API di Content delivery/preview tokens . Catatan Nilai token akses Space ID dan Content Delivery API yang akan Anda gunakan untuk menghubungkan lingkungan Stacy Anda ke ruang Contentful Anda.
Sekarang, Anda dapat membuat proyek awal untuk situs web Anda:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Ini akan membuat direktori proyek baru bernama "situs web saya" di direktori saat ini. Nilai "situs web saya" dikenal sebagai ID situs . Gunakan nilai berbeda yang mengidentifikasi situs web Anda. Nilainya harus bersifat URL-fiendly (huruf kecil, angka, dan tanda hubung).
Di direktori proyek Anda, letakkan konten statis di bawah /static (ini akan disalin ke situs web Anda sebagaimana adanya) dan letakkan templat entri Anda di bawah /templates . Nama file templat (tanpa ekstensi) harus sama persis dengan jenis konten entri yang sesuai dalam model Contentful Content Anda. Di bawah /templates , file template dapat diatur dalam subfolder. Namun, nama file harus unik di semua subfolder karena digunakan untuk mencocokkan template secara unik dengan tipe konten entri (subfolder di /templates tidak berperan).
Catatan: Biasanya, template, dikombinasikan dengan konten entri, menghasilkan HTML. Jika Anda perlu membuat beberapa jenis konten lain, Anda dapat menambahkan ekstensi ke nama templat. Misalnya, page.hbs menghasilkan HTML. Untuk menghasilkan teks biasa gunakan page.txt.hbs . Ini juga berarti page.hbs dan page.html.hbs adalah sama.
Anda sekarang dapat menjalankan situs web Anda secara lokal untuk tujuan pengembangan:
stacy serve
Anda dapat melihat situs web Anda di http://localhost:8080/ . Setelah Anda mengedit template, konten statis, atau konten apa pun di Contentful, cukup muat ulang halamannya.
Untuk menghentikan penggunaan server web lokal Stacy Ctrl+C .
Jalankan stacy --help untuk melihat perintah lain yang tersedia.
Konten direktori proyek Anda dapat Anda periksa ke repositori git seperti GitHub atau Bitbucket.
Di dalam templat Anda, semua bidang entri tersedia berdasarkan ID Bidang seperti yang ditentukan dalam model Konten Anda. Anda dapat mereferensikannya langsung di template Anda. Misalnya:
Ini akan menampilkan nilai bidang caption entri. Perhatikan, yang digunakan di sini adalah Field ID dan bukan field Name .
Stacy menambahkan beberapa pembantu khusus yang dapat Anda gunakan di templat Anda:
module <reference field> - Sertakan entri modul yang direferensikan oleh bidang Jenis referensi. Misalnya, Anda memiliki bidang dengan paragraphs ID dan itu adalah daftar referensi:
asset <asset field> - Sertakan aset yang dirujuk, seperti gambar. Misalnya:
Saat ini, hanya aset gambar yang didukung, yang mana tag HTML <img> dirender.
assetSrc <asset field> - Dapatkan URL aset. Misalnya:
assetTitle <asset field> - Dapatkan judul aset. Misalnya:
markdown <long text field> - Render bidang teks panjang Penurunan harga. Misalnya:
Perhatikan kurung kurawal rangkap tiga yang diperlukan di sini karena helper menghasilkan HTML yang tidak perlu di-escape.
richText <rich text field> - Merender bidang teks kaya. Misalnya:
Seperti halnya markdown , perhatikan tanda kurung kurawal rangkap tiga.
json <field> - Output representasi JSON Contentful internal dari bidang tersebut. Misalnya:
Penolong ini mungkin berguna untuk mendiagnosis masalah.
Seperti disebutkan di atas, ada hubungan satu-ke-satu antara tipe konten yang Anda tentukan di model dan templat Konten ruang Contentful Anda.
Catatan: Sebenarnya, Anda bisa memiliki lebih dari satu templat untuk tipe konten tertentu guna memungkinkan pembuatan tipe file berbeda untuk entri konten yang sama. Misalnya, untuk module ID tipe konten, Anda dapat memiliki templat module.html.hbs dan module.xml.hbs . Templat pertama akan menghasilkan file HTML untuk entri dan templat kedua akan menghasilkan file XML.
Saat Anda menentukan tipe konten, perhatikan Pengidentifikasi Api (juga dikenal sebagai ID tipe konten ). File templat untuk tipe konten harus memiliki nama yang sama (ditambah ekstensinya).
Ada satu persyaratan untuk tipe konten untuk entri halaman (sebagai lawan entri modul): tipe konten halaman harus menentukan bidang slug yang diperlukan. Nilai di bidang tersebut akan menentukan nama file yang dihasilkan ketika entri konten digabungkan dengan templat yang sesuai. Misalnya, jika nilai slug untuk entri halaman adalah "indeks", halaman yang dihasilkan akan menjadi "/index.html". Jika slugnya adalah "more/terms", halamannya akan menjadi "/more/terms.html". Dan sebagainya.
Secara default, ID bidang untuk bidang slug harus slug . ID dapat diganti di file stacy.json proyek. Selain membuat bidang slug diperlukan dalam definisi tipe konten, disarankan juga untuk mengaitkan validator pola pencocokan kustom dengannya untuk memastikan format spesifik nilai bidang. Ekspresi reguler untuk validator dapat berupa ^w[w-]*(/w[w-]*)*$ .
Saat Anda siap untuk menerapkan situs web Anda di AWS, Anda harus terlebih dahulu menyiapkan infrastruktur Stacy di akun AWS Anda. Anda harus melakukan beberapa langkah sebelum dapat melakukannya:
Buat bucket S3 target. Di sinilah situs web Anda akan dipublikasikan dan dari sana akan disajikan (mungkin melalui CloudFront). Alternatifnya, Anda dapat menggunakan bucket yang sudah Anda miliki (Stacy juga mendukung penerbitan dalam subfolder di bucket target).
Jika Anda belum memilikinya, buatlah bucket S3 yang akan digunakan Stacy untuk mengunggah paket fungsi penerbit Lambda. Fungsi penerbit Lambda adalah bagian yang merespons peristiwa publikasi dan pembatalan publikasi Contentful serta memperbarui halaman dan aset yang relevan di bucket S3 target.
Bangun paket penerbit:
stacy build-publisher
Ini akan membuat paket fungsi penerbit Lambda di proyek Anda di bawah /build/stacy-mywebsite-publisher.zip . Unggah file ini ke bucket S3 fungsi Lambda Anda.
Perintah stacy new Stacy telah menghasilkan templat CloudFormation untuk lingkungan AWS dan menyimpannya dalam proyek Anda di bawah /misc/cfn-template.json . Anda dapat meninjau dan menyesuaikannya jika perlu. Jika tidak, lanjutkan dan buat tumpukan Stacy untuk situs web Anda di bawah akun AWS Anda.
Setelah tumpukan CloudFormation dibuat, Anda perlu menyesuaikan kebijakan bucket S3 target untuk mengizinkan penerbit Stacy mempublikasikan konten situs web yang dihasilkan di dalamnya. Kebijakan bucket dapat mencakup hal seperti berikut:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} Dalam kebijakan di atas, ganti ARN peran penerbit Stacy dengan nilai yang dapat Anda temukan di parameter output PublisherRoleArn tumpukan CloudFormation Anda, dan nama bucket dengan nama bucket situs web target (bucket tempat kebijakan diterapkan).
Sekarang Anda harus mempersiapkan lingkungan pengembangan untuk penerbitan. Buka dan edit file .env di proyek situs web Anda. Di dalamnya, atur semua variabel AWS_* ke nilai yang benar. Perhatikan, Anda dapat menemukan nilai untuk variabel AWS_PUBLISH_EVENT_SOURCE_MAPPING di parameter output PublishEventSourceMappingId tumpukan CloudFormation.
Setelah file .env Anda disiapkan dengan benar, Anda dapat mempublikasikan situs web Anda menggunakan:
stacy publish
Satu langkah penyiapan terakhir adalah mengonfigurasi webhook di ruang Contentful Anda untuk memanggil penerbit Stacy saat menerbitkan dan membatalkan penerbitan acara. Di akun AWS Anda, di layanan API Gateway, temukan API yang dibuat untuk Anda oleh Stacy. Hanya ada satu metode POST /publish di tahap prod API. Catat URL Invoke -nya.
Juga, buka bagian Kunci API dan catat nilai kunci API yang dibuat untuk Stacy.
Di ruang Contentful Anda, buka Pengaturan ruang→Webhook dan tambahkan webhook. Masukkan URL pemanggilan API Gatwey di bidang URL (tinggalkan metode POST ). Kemudian pilih opsi Pilih peristiwa pemicu tertentu di bagian Pemicu . Centang kotak Terbitkan dan Batalkan Publikasi di baris Entri dan Aset (4 kotak centang dicentang seluruhnya).
Di bagian Header klik Tambahkan header rahasia . Masukkan "X-API-Key" di bidang Kunci dan di bidang Nilai masukkan kunci API dari API Gateway.
Setelah Anda menyimpan webhook ini, penerbitan dan penghapusan entri dan aset di Contentful akan memicu penerbit dalam pengaturan AWS dan Anda sudah siap!
