baker example page template
1.0.0
Demonstrasi tentang cara membuat dan menerbitkan halaman dengan alat pembuat pembuat roti.
The Los Angeles Times menggunakan pembuat roti untuk membuat halaman statis yang diterbitkan di latimes.com/projects. Sistem Times mengandalkan versi pribadi dari repositori seperti ini. Contoh sederhana ini menerbitkan versi pementasan dan produksi ke bucket publik di Amazon S3.
Server uji lokal yang diperbarui secara langsung
Templat HTML dengan Nunjucks
CSS yang diperluas dengan Sass
Bundel JavaScript dengan Rollup dan Babel
Impor data dengan quaff
Pembuatan halaman dinamis berdasarkan masukan terstruktur
Penerapan otomatis setiap cabang ke lingkungan pementasan pada setiap peristiwa push melalui GitHub Action
Penerapan tombol tekan ke lingkungan produksi pada setiap peristiwa release melalui GitHub Action
Pesan kendur yang menyampaikan setiap status penerapan melalui datadesk/notify-slack-on-build Github Action
Node.js versi 12, 14 atau 16, meskipun minimal 12.20, 14.14, atau 16.0.
Manajer Paket Node
git
Dengan sedikit konfigurasi, Anda dapat menggunakan template ini untuk mempublikasikan halaman dengan mudah. Dengan sedikit penyesuaian, Anda dapat membuatnya terlihat sesuai keinginan Anda. Panduan ini akan memperkenalkan Anda pada dasar-dasarnya.
Membuat halaman baru
Menjelajahi repositori
Mengakses aset
Mengakses data
Halaman dinamis
Penyebaran
Variabel global
baker.config.js
Langkah pertama adalah mengklik tombol “gunakan templat ini” di GitHub untuk membuat salinan repositori untuk Anda sendiri.
Anda akan diminta memberikan slug untuk proyek Anda. Setelah selesai, repositori baru akan tersedia di https://github.com/your-username/your-slug .
Selanjutnya Anda harus mengkloningnya ke komputer Anda agar dapat bekerja dengan kode tersebut.
Buka terminal Anda dan cd ke folder kode Anda. Kloning proyek ke dalam folder Anda. Ini akan menyalin proyek ke komputer Anda.
git clone https://github.com/nama-pengguna-anda/slug-anda
Jika perintah tersebut tidak berhasil untuk Anda, mungkin karena komputer Anda dikonfigurasi secara berbeda dan Anda perlu mengkloning ke repositori menggunakan SSH. Coba jalankan ini di terminal Anda:
git clone [email protected]:nama-pengguna-anda/slug-anda.git
Setelah repositori selesai diunduh, cd ke slug Anda dan instal dependensi Node.js.
instalasi npm
Setelah dependensi diinstal, Anda siap melihat pratinjau proyek. Jalankan perintah berikut untuk memulai server pengujian.
npm mulai
Sekarang buka localhost:3000 di browser Anda. Anda akan melihat halaman boilerplate yang siap untuk penyesuaian Anda.
Cara alternatifnya adalah dengan membuat halaman baru dengan bluprint, alat scaffolding baris perintah yang dikembangkan oleh departemen grafis Reuters.
cetak biru tambahkan https://github.com/datadesk/baker-example-page-template mkdir halaman-baru-sayacd halaman-baru-saya cetak biru mulai halaman contoh pembuat roti
Berikut adalah file dan folder standar yang akan Anda temukan saat mengkloning proyek baru dari templat halaman kami. Anda akan menghabiskan lebih banyak waktu mengerjakan beberapa file dibandingkan file lainnya, namun ada baiknya jika Anda memiliki gambaran umum tentang apa yang dilakukan file-file tersebut.
Folder data berisi data yang relevan untuk proyek tersebut. Kami menggunakan folder ini untuk menyimpan informasi yang diperlukan tentang setiap proyek — seperti di URL mana proyek tersebut seharusnya berada. Anda juga dapat menyimpan berbagai tipe data lainnya di sini, termasuk .aml , .csv , dan .json .
File meta.aml berisi informasi penting tentang halaman seperti judul, byline, slug, tanggal publikasi, dan bidang lainnya. Mengisinya memastikan halaman Anda ditampilkan dengan benar dan dapat diindeks oleh mesin pencari. Daftar lengkap semua atribut dapat ditemukan di bahan referensi kami. Anda dapat memperluasnya untuk menyertakan opsi sebanyak atau sesedikit yang Anda inginkan.
Folder ini menyimpan templat dasar situs kami dan cuplikan kode yang dapat digunakan kembali. Saat Anda memulai, kemungkinan besar Anda tidak akan mengubah apa pun di sini. Dalam kasus penggunaan lebih lanjut, ini adalah tempat Anda dapat menyimpan kode yang digunakan kembali di beberapa halaman.
base.htmlFile base.html berisi semua HTML dasar yang ditemukan di setiap halaman yang kita buat. Contoh di sini adalah desain yang belum sempurna. Anda mungkin ingin menyertakan lebih banyak hal dalam implementasi dunia nyata.
Ruang kerja adalah tempat Anda meletakkan segala sesuatu yang relevan dengan proyek yang tidak perlu dipublikasikan di web. File AI, potongan kode, tulisan, dll. Terserah Anda.
Ini digunakan untuk menyimpan media dan aset lainnya seperti gambar, video, audio, font, dll. Mereka dapat ditarik ke halaman melalui tag template static .
File JavaScript disimpan di folder ini. File utama untuk JavaScript disebut app.js , tempat Anda dapat menulis kode secara langsung. Paket yang diinstal melalui npm dapat diimpor dan dijalankan seperti skrip Node.js lainnya. Anda dapat membuat file lain untuk menulis kode JavaScript di folder ini, tetapi Anda harus memastikan bahwa file tersebut di-boot dari app.js .
Stylesheet kami ditulis dalam SASS, bahasa stylesheet canggih yang memberi pengembang kontrol lebih besar atas CSS. Jika Anda merasa tidak nyaman dengan SASS, Anda dapat menulis CSS biasa ke dalam stylesheet.
Folder gaya terdiri dari lembar gaya ( app.scss ) tempat Anda dapat menambahkan semua gaya khusus ke proyek Anda, meskipun terkadang Anda mungkin ingin membuat lembar gaya tambahan dan mengimpornya ke app.scss . Proyek contoh ini hanya mencakup simulasi minimum yang diperlukan untuk situs sederhana. Anda mungkin ingin memulai dengan lebih banyak penerapan di dunia nyata.
File baker.config.js adalah tempat kami meletakkan opsi yang digunakan Baker untuk melayani dan membangun proyek. Ini telah didokumentasikan sepenuhnya di tempat lain dalam file ini. Dengan pengecualian pengaturan domain , hanya pengguna tingkat lanjut yang perlu mengubah file ini.
Templat default untuk halaman Anda. Di sinilah Anda akan menata halaman Anda. Ia menggunakan sistem templating Nujucks untuk membuat HTML.
File-file ini melacak dependensi Node yang digunakan dalam proyek kami. Saat Anda menjalankan npm install perpustakaan yang Anda tambahkan akan secara otomatis dilacak di sini untuk Anda.
Ini adalah direktori khusus untuk menyimpan file yang digunakan GitHub untuk berinteraksi dengan proyek dan kode kami. Direktori .github/workflows berisi Tindakan GitHub yang menangani penerapan pengembangan kami. Anda tidak perlu mengedit apa pun di sini.
Penyimpanan file di direktori aset dioptimalkan dan di-hash sebagai bagian dari proses penerapan. Untuk memastikan bahwa referensi Anda ke gambar dan file statis lainnya, Anda harus menggunakan tag {% static %} . Hal ini memastikan file disimpan dalam cache dalam jumlah besar saat dipublikasikan dan tautan ke gambar berfungsi di semua lingkungan. Anda pasti ingin menggunakannya untuk semua foto dan video.
<gambar>
<img src="{% static 'assets/images/baker.jpg' %}" alt="Logo pembuat roti" width=200>
</gambar> File data terstruktur yang disimpan di folder _data Anda dapat diakses melalui templatetags atau JavaScript. Dalam demonstrasi ini, file bernama example.json telah disertakan untuk mengilustrasikan kemungkinan tersebut. Format file lain seperti CSV, YAML dan AML didukung.
File di folder _data tersedia berdasarkan namanya di dalam templat Anda. Jadi, dengan _data/example.json , Anda dapat menulis sesuatu seperti:
{% untuk objek misalnya %}
{{ obj.tahun }}: {{ obj.gandum }}{% endfor %}Kebutuhan umum bagi siapa pun yang membangun proyek di Baker adalah akses ke data mentah dalam file JavaScript. Seringkali data ini kemudian diteruskan ke kode yang ditulis menggunakan d3 atau Svelte untuk menggambar grafik atau membuat tabel HTML pada halaman.
Jika data yang Anda akses sudah tersedia di URL yang Anda yakini akan tetap aktif, hal ini mudah dilakukan. Namun bagaimana jika ternyata tidak, dan itu adalah data yang Anda persiapkan sendiri?
Dimungkinkan untuk mengakses catatan di folder _data Anda. Satu-satunya peringatan adalah tugas mengubah file ini menjadi kondisi yang dapat digunakan adalah tanggung jawab Anda. Perpustakaan yang bagus untuk ini adalah d3-fetch .
Untuk membuat URL ke file ini dengan cara yang dipahami Baker, gunakan format ini:
import { json } dari 'd3-fetch';// parameter pertama harus berupa path ke file// parameter kedua *harus* berupa “import.meta.url”const url = new URL('../_data /example.json', import.meta.url);// Sebut saja inconst data = menunggu json(url); Pendekatan lain adalah dengan mencetak data ke dalam templat Anda sebagai tag script . Filter jsonScript mengambil variabel yang diteruskan ke sana, menjalankan JSON.stringify di atasnya, dan mengeluarkan JSON ke dalam HTML dalam tag <script> dengan ID yang ditetapkan di dalamnya yang Anda teruskan sebagai parameter.
{{ contoh|jsonScript('contoh-data') }}Setelah itu diterapkan, Anda sekarang dapat mengambil JSON yang disimpan di halaman berdasarkan ID di JavaScript Anda.
// ambil elemen jsonScript yang dibuat dengan menggunakan ID yang sama dengan yang Anda berikan inconst dataElement = document.getElementById('example-data');// ubah konten elemen tersebut menjadi JSON// lakukan apa yang perlu Anda lakukan dengan “data” !const data = JSON.parse(dataElement.textContent); Meskipun metode URL direkomendasikan, metode ini mungkin masih lebih disukai ketika Anda mencoba menghindari permintaan jaringan tambahan. Ini juga memiliki keuntungan tambahan karena tidak memerlukan perpustakaan khusus untuk mengonversi data .csv menjadi JSON.
Anda dapat membuat halaman statis dalam jumlah tak terbatas dengan memasukkan sumber data terstruktur ke opsi createPages di file baker.config.js . Misalnya, cuplikan ini akan menghasilkan halaman untuk setiap catatan di file example.json .
ekspor bawaan {
// ... semua opsi lain di atas yang satu ini telah dikecualikan untuk memperjelas maksudnya
createPages: createPages(createPage, data) {// Ambil data dari folder _dataconst pageList = data.example;// Ulangi recordfor (const d dari pageList) { // Tetapkan templat dasar yang akan digunakan untuk setiap objek . Ada di folder _layouts const template = 'year-detail.html'; // Tetapkan URL untuk halaman const url = `${d.year}`; // Tetapkan variabel yang akan dimasukkan ke dalam konteks templat const konteks = { obj: d }; // Gunakan fungsi yang disediakan untuk merender halaman createPage(template, url, konteks);}
},}; Itu dapat digunakan untuk membuat URL seperti /baker-example-page-template/1775/ dan /baker-example-page-template/1780/] dengan satu template.
Sebelum Anda dapat menerapkan halaman yang dibuat oleh repositori ini, Anda perlu mengonfigurasi akun Amazon AWS Anda dan menambahkan satu set kredensial ke akun GitHub Anda.
Pertama, Anda harus membuat dua bucket di layanan penyimpanan S3 Amazon. Salah satunya adalah untuk situs pementasan Anda. Yang lainnya adalah untuk situs produksi Anda. Untuk contoh sederhana ini, masing-masing harus mengizinkan akses publik dan dikonfigurasi untuk melayani situs web statis. Dalam pengaturan yang lebih canggih, seperti yang kami jalankan di Los Angeles Times, keranjang tersebut dapat dihubungkan dengan nama domain terdaftar dan situs pementasan terlindung dari pandangan publik melalui skema otentikasi.
Nama-nama bucket tersebut kemudian harus disimpan sebagai "rahasia" GitHub yang dapat diakses oleh Actions yang menyebarkan situs tersebut. Anda harus mengunjungi panel pengaturan untuk akun atau organisasi Anda. Mulailah dengan menambahkan dua rahasia ini.
| Nama | Nilai |
|---|---|
BAKER_AWS_S3_STAGING_BUCKET | Nama wadah pementasan Anda |
BAKER_AWS_S3_STAGING_REGION | Wilayah S3 tempat staging bucket Anda dibuat |
BAKER_AWS_S3_PRODUCTION_BUCKET | Nama bucket produksi Anda |
BAKER_AWS_S3_PRODUCTION_REGION | Wilayah S3 tempat bucket produksi Anda dibuat |
Selanjutnya Anda harus memastikan bahwa Anda memiliki pasangan kunci dari AWS yang memiliki kemampuan untuk mengunggah file publik ke dua keranjang Anda. Nilai-nilainya juga harus ditambahkan ke rahasia Anda.
| Nama | Nilai |
|---|---|
BAKER_AWS_ACCESS_KEY_ID | Kunci akses AWS |
BAKER_AWS_SECRET_ACCESS_KEY | Kunci rahasia AWS |
Tindakan GitHub yang disertakan dengan repositori ini akan secara otomatis menerbitkan versi pementasan untuk setiap cabang. Misalnya, kode yang dimasukkan ke cabang main default akan muncul di https://your-staging-bucket-url/your-repo/main/ .
Jika Anda membuat cabang git baru bernama bugfix dan memasukkan kode Anda, Anda akan segera melihat versi pementasan baru di https://your-staging-bucket-url/your-repo/bugfix/ .
Sebelum Anda mengirimkan halaman Anda secara langsung, Anda harus menentukan slug terakhir untuk URL-nya. Ini akan mengatur subdirektori di keranjang Anda tempat halaman akan dipublikasikan. Fitur ini memungkinkan The Times untuk menerbitkan banyak halaman dalam wadah yang sama dengan setiap halaman dikelola oleh repositori berbeda.
Langkah pertama adalah memasukkan slug untuk URL Anda ke dalam file konfigurasi _data/meta.aml .
siput: siput halaman Anda
Bukan ide yang buruk untuk memastikan siput Anda belum diambil. Anda dapat melakukannya dengan mengunjungi https://your-production-bucket-url/your-slug/ dan memastikan ia mengembalikan kesalahan halaman tidak ditemukan.
Jika Anda ingin mempublikasikan halaman Anda di root bucket Anda, Anda dapat membiarkan slugnya null.
siput:
Selanjutnya Anda mengkomit perubahan Anda ke file konfigurasi dan memastikannya dikirim ke cabang utama di GitHub.
git tambahkan _data/meta.aml git commit -m “Setel siput halaman” git push asal utama
Kunjungi bagian rilis pada halaman repositori Anda di GitHub. Anda dapat menemukannya di beranda repo.
Draf rilis baru.
Di sana Anda akan membuat nomor tag baru. Pendekatan yang baik adalah memulai dengan nomor format xxx yang mengikuti standar versi semantik. 1.0.0 adalah awal yang baik.
Terakhir, tekan tombol hijau besar di bagian bawah dan kirimkan rilisnya.
Tunggu beberapa menit dan halaman Anda akan muncul di https://your-production-bucket-url/your-slug/ .
Server uji pembuat roti dapat mencatat dengan lebih detail dengan memulai dengan opsi berikut.
DEBUG=1 npm mulai
Untuk membatasi log agar dijalankan oleh pembuat roti:
DEBUG=tukang roti:* npm mulai
Jika pembangunan Anda tidak berhasil, Anda dapat mencoba membuat sendiri situs statis secara lokal melalui terminal Anda. Jika ada kesalahan dalam pembuatan halaman, kesalahan tersebut akan dicetak ke terminal Anda.
npm jalankan pembangunan
Baker hadir dengan sekumpulan variabel global yang sama di setiap halaman yang dibuatnya, dan kumpulan variabel khusus halaman lainnya yang disetel berdasarkan halaman yang sedang dibuat. Anda dapat menggunakan variabel ini untuk menambahkan konten ke halaman secara kondisional atau memfilter data yang tidak terkait berdasarkan halaman saat ini.
NODE_ENV Variabel NODE_ENV akan selalu berupa salah satu dari dua nilai: development atau production . Ini sesuai dengan jenis build yang dijalankan pada halaman.
Saat Anda menjalankan npm start , Anda berada dalam mode development . Saat Anda menjalankan npm run build , Anda berada dalam mode production .
Ini paling berguna untuk menambahkan sesuatu ke halaman hanya ketika Anda berada dalam mode development .
{% if NODE_ENV == 'development' %}<p>Anda tidak akan pernah melihat ini di situs langsung!</p>{% endif %}DOMAIN Variabel DOMAIN akan selalu sama dengan opsi domain yang diteruskan baker.config.js , atau string kosong jika tidak diteruskan.
PATH_PREFIX Variabel PATH_PREFIX akan selalu sama dengan opsi pathPrefix yang diteruskan di baker.config.js , atau satu garis miring ( / ) jika tidak ada yang diteruskan.
page.url URL relatif proyek ke halaman saat ini. Akan menyertakan pathPrefix jika ada yang disediakan di file baker.config.js — dengan kata lain, ini akan memperhitungkan setiap jalur proyek yang sedang dilakukan dan mengarah ke halaman yang benar dalam proyek tersebut.
page.absoluteUrl URL absolut ke halaman saat ini. Ini menggabungkan domain , pathPrefix dan jalur saat ini menjadi URL lengkap. Saat ini digunakan untuk menampilkan URL kanonik dan semua URL untuk tag <meta> sosial.
<link rel="canonical" href="{{ page.absoluteUrl }}">page.inputUrl Ini adalah jalur ke templat asli yang digunakan untuk membuat halaman ini relatif terhadap direktori proyek saat ini. Jika Anda memiliki file HTML yang terletak di page-two/index.html , page.inputUrl akan menjadi page-two/index.html .
page.outputUrl Ini adalah jalur ke file HTML yang dihasilkan untuk membuat halaman ini relatif terhadap folder _dist . Jika Anda memiliki file HTML yang terletak di page-two.html , page.outputUrl akan menjadi page-two/index.html .
Setiap proyek Baker yang kami kerjakan menyertakan file baker.config.js di direktori root. File ini bertanggung jawab untuk meneruskan informasi ke Baker sehingga dapat membangun proyek Anda dengan benar.
ekspor bawaan {
// direktori tempat aset berada
aset: 'aset',
// buatHalaman
buatHalaman: tidak terdefinisi,
// direktori data
data: '_data',
// domain kustom opsional untuk digunakan dalam pembuatan jalur
domain: tidak terdefinisi,
// jalur atau kumpulan jalur dari setiap titik masuk JavaScript
titik masuk: 'scripts/app.js',
// direktori masukan keseluruhan, biasanya folder saat ini
masukan: proses.cwd(),
// tempat tata letak templat, makro, dan penyertaannya berada
tata letak: '_layout',
// sebuah objek dengan kunci dan nilai variabel global
// diteruskan ke semua template Nunjucks
nunjucksVariabel: tidak terdefinisi,
// objek kunci (nama) + nilai (fungsi) untuk menambahkan kustom
// memfilter ke Nunjucks
nunjucksFilters: tidak terdefinisi,
// objek kunci (nama) + nilai (fungsi) untuk menambahkan kustom
// memberi tag ke Nunjucks
nunjucksTag: tidak terdefinisi,
// di mana menampilkan file yang dikompilasi
keluaran: '_dist',
// awalan untuk ditambahkan ke awal setiap jalur yang diselesaikan, caranya
// siput berfungsi
jalurAwalan: '/',
// direktori opsional untuk menyimpan semua aset, jarang digunakan
akar statis: '',}; bawaan: ”assets”
Ini memberitahu Baker folder mana yang harus diperlakukan sebagai direktori aset. Anda mungkin tidak perlu mengubahnya.
bawaan: undefined
createPages adalah parameter opsional yang memungkinkan pembuatan halaman secara dinamis menggunakan data dan templat dalam proyek.
ekspor bawaan {
// …
// createPage - memasukkan templat, nama keluaran, dan konteks data
// data - data yang disiapkan di folder `_data`
createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
},}; bawaan: ”_data”
Opsi data memberitahu Baker folder mana yang harus diperlakukan sebagai sumber datanya. Anda mungkin tidak perlu mengubahnya.
bawaan: undefined
Opsi domain memberi tahu Baker apa yang harus digunakan saat membuat URL absolut. bakery-template menyetelnya ke https://www.latimes.com .
default: ”scripts/app.js”
Opsi entrypoints memberi tahu Baker file JavaScript apa yang harus diperlakukan sebagai titik awal untuk bundel skrip. Ini bisa berupa jalur ke file atau glob file, sehingga memungkinkan untuk membuat beberapa bundel secara bersamaan.
default: process.cwd()
Opsi input memberitahu Baker folder mana yang harus diperlakukan sebagai direktori utama untuk keseluruhan proyek. Secara default, ini adalah folder tempat file baker.config.js berada. Anda mungkin tidak perlu mengaturnya.
bawaan: ”_layouts”
Opsi layouts memberi tahu Baker di mana templat, penyertaan, dan makro berada. Secara default, ini adalah folder _layouts . Anda mungkin tidak perlu mengatur ini.
bawaan: undefined
Anda dapat menggunakan nunjucksFilters untuk meneruskan filter khusus Anda sendiri. Dalam objek, setiap kunci adalah nama filter, dan nilai fungsi adalah apa yang dipanggil saat Anda menggunakan filter.
ekspor bawaan {
// ...
// meneruskan objek filter untuk ditambahkan ke Nunjucks
nunjucksFilter: {persegi(n) { n = +n; kembali n * n;}
},} {{ nilai|persegi }} bawaan: undefined
Anda dapat menggunakan nunjucksTags untuk meneruskan tag khusus Anda sendiri. Ini berbeda dari filter karena memudahkan keluaran blok teks atau HTML.
ekspor bawaan {
// ...
// meneruskan objek filter untuk ditambahkan ke Nunjucks
nunjucksTags: {doubler(n) { return `<p>${n} dua kali lipat adalah ${n * 2}</p>`;}
},}; {% nilai pengganda %} bawaan: ”_dist”
Opsi output memberitahu Baker di mana harus meletakkan file ketika npm run build dijalankan. Secara default ini adalah folder _dist . Anda mungkin tidak perlu mengatur ini.
bawaan: ”/”
pathPrefix memberi tahu Baker awalan jalur apa yang harus ditambahkan ke URL apa pun yang dibuatnya. Jika domain juga diteruskan, domain tersebut akan digabungkan dengan pathPrefix saat membuat URL absolut. Anda biasanya tidak akan menyetelnya secara manual — ini digunakan selama penerapan untuk membuat URL dengan slug proyek.
bawaan: ””
Opsi staticRoot menginstruksikan Baker untuk meletakkan semua aset di direktori tambahan. Hal ini berguna untuk proyek yang perlu memiliki slug unik di setiap halaman tanpa membuat sarang, sehingga memungkinkan mereka semua berbagi aset statis. Namun — ini adalah kasus khusus dan memerlukan pengaturan khusus untuk penerapannya. Jangan mencoba menggunakan ini tanpa alasan yang jelas.
