Tutorial Hugo Shortcodes: Membuat Konten Dinamis dengan Shortcode
Tutorial Hugo Shortcodes: Membuat Konten Dinamis dengan Shortcode
Shortcodes adalah fitur powerful di Hugo yang memungkinkan Anda menyisipkan konten dinamis atau kompleks ke dalam konten markdown tanpa harus menulis kode HTML secara langsung. Dalam tutorial ini, kita akan mempelajari berbagai aspek shortcodes, mulai dari penggunaan shortcodes bawaan Hugo hingga pembuatan shortcode custom sesuai kebutuhan spesifik website Anda.
Bayangkan Anda ingin menyematkan video YouTube di tengah artikel. Tanpa shortcodes, Anda harus menyalin embed code HTML yang panjang dan rumit. Dengan shortcodes, cukup gunakan {{ < youtube idnya >}} dan Hugo akan merender embed yang benar. Shortcodes juga memungkinkan Anda membuat komponen reusable seperti gallery gambar, alert boxes, atau call-to-action buttons dengan sintaksis yang sederhana di markdown.
Memahami Konsep Shortcodes
Shortcodes di Hugo bekerja dengan prinsip sederhana: mereka adalah template khusus yang dipanggil dari konten markdown menggunakan sintaksis khusus. Ketika Hugo membangun situs, shortcodes ini dirender menjadi HTML final. Ada dua jenis shortcodes utama di Hugo: shortcode single tag yang tidak memiliki closing tag, dan shortcode container yang memiliki opening dan closing tag.
Sintaksis shortcode Hugo menggunakan kurung kurawal ganda dengan tanda persen atau pipa. Tanda persen (%) digunakan untuk shortcodes dengan akses ke konteks lengkap, sementara tanda pipa (|) digunakan untuk shortcodes dengan parameter parsial. Berikut perbedaannya: {{ < shortcode > }} untuk single tag dengan konteks penuh, dan {{ % shortcode % }} untuk single tag dengan konteks parsial. Untuk container: {{ < shortcode > }}...content...{{ < /shortcode > }} dan {{ % shortcode % }}...content...{{ % /shortcode % }}.
Shortcodes Bawaan Hugo
Hugo menyediakan beberapa shortcodes bawaan yang sangat berguna untuk kebutuhan umum. Memahami dan menggunakan shortcodes ini akan sangat membantu dalam membuat konten yang kaya dan interaktif.
Shortcode YouTube
Shortcode YouTube adalah salah satu yang paling sering digunakan. Cara penggunaannya sangat sederhana:
{{ < youtube id_videonya >}}
Atau dengan parameter tambahan untuk mengatur ukuran dan autoplay:
{{ < youtube id_videonya width="640" height="360" autoplay="true" muted="false" loop="true" playlist="id_videonya" start="30" end="120" parameters="rel=0" >}}
Parameter id wajib diisi dengan ID video dari URL YouTube. Parameter opsional meliputi width dan height untuk ukuran embed, autoplay untuk autoplay saat dimuat, mute untuk mute secara default, loop untuk loop video, playlist untuk playlist ID, start dan end untuk waktu mulai dan berakhir dalam detik, serta parameters untuk parameter URL tambahan.
Shortcode Vimeo
Untuk video Vimeo, Hugo menyediakan shortcode khusus:
{{ < vimeo id_videonya >}}
{{ < vimeo id_videonya width="640" height="360" title="1" byline="1" portrait="1" color="ff0000" autoplay="false" loop="true" api="1" player_id="0" >
Shortcode Figure
Shortcode figure adalah enhanced version dari image markdown standar dengan fitur tambahan seperti caption, link, dan class kustom:
{{ < figure src="/images/foto.webp" title="Judul Gambar" caption="Ini adalah caption gambar" link="/images/foto.webp" target="_blank" class="rounded-lg shadow-lg" width="600" height="400" attr="Attribution text" attrlink="https://attribution.com" loading="lazy" alt="Deskripsi untuk aksesibilitas" >}}
Shortcode Instagram
Untuk menyematkan post Instagram:
{{ < instagram id_postnya >}}
Shortcode Twitter
Untuk menyematkan tweet:
{{ < tweet id_tweetnya >}}
Shortcode GitHub Gist
Untuk menampilkan Gist dari GitHub:
{{ < gist username gist_id filename >}}
{{ < gist user 1234567 file.js >}}
Membuat Shortcode Custom
Selain shortcode bawaan, Hugo memungkinkan Anda membuat shortcode custom sesuai kebutuhan spesifik website. Shortcode custom dibuat sebagai file template di folder layouts/shortcodes/.
Shortcode Alert Box
Mari kita mulai dengan membuat shortcode alert box yang sering digunakan untuk menampilkan informasi penting:
{{/* layouts/shortcodes/alert.html */}}
{{- $type := .Get "type" | default "info" -}}
{{- $icon := .Get "icon" | default false -}}
<div class="alert alert-{{ $type }}" role="alert">
{{- if $icon -}}
<span class="alert-icon">{{ $icon }}</span>
{{- end -}}
<div class="alert-content">
{{ .Inner | .Page.RenderString | emojify }}
</div>
</div>
Penggunaan di konten markdown:
{{ < alert type="warning" icon="⚠️" >}}
Perhatikan langkah-langkah berikut dengan seksama.
{{ < /alert >}}
{{ < alert type="success" icon="✅" >}}
Selamat! Proses berhasil diselesaikan.
{{ < /alert >}}
{{ < alert type="danger" icon="❌" >
Peringatan: Data tidak dapat dipulihkan setelah dihapus.
{{ < /alert >}}
{{ < alert type="info" >
Ini adalah informasi umum tanpa icon khusus.
{{ < /alert >}}
CSS untuk alert box:
.alert {
padding: 1rem;
border-radius: 0.5rem;
margin: 1rem 0;
display: flex;
gap: 0.75rem;
}
.alert-info { background-color: #dbeafe; border: 1px solid #3b82f6; color: #1e40af; }
.alert-success { background-color: #dcfce7; border: 1px solid #22c55e; color: #166534; }
.alert-warning { background-color: #fef9c3; border: 1px solid #eab308; color: #854d0e; }
.alert-danger { background-color: #fee2e2; border: 1px solid #ef4444; color: #991b1b; }
Shortcode Gallery Gambar
Shortcode gallery memungkinkan menampilkan multiple gambar dalam grid yang responsif:
{{/* layouts/shortcodes/gallery.html */}}
{{- $columns := .Get "columns" | default 3 -}}
{{- $class := .Get "class" | default "" -}}
<div class="gallery gallery-{{ $columns }} {{ $class }}">
{{- range where .Page.Resources.ByType "image" "Src" .Inner -}}
<figure class="gallery-item">
<a href="{{ .Permalink }}" data-lightbox="gallery">
<img src="{{ .Resize "400x webp" .Permalink }}"
alt="{{ .Title }}"
loading="lazy"
width="{{ .Width }}"
height="{{ .Height }}">
</a>
{{- with .Title -}}
<figcaption>{{ . }}</figcaption>
{{- end -}}
</figure>
{{- end -}}
</div>
Penggunaan:
{{ < gallery columns="4" class="my-gallery" >}}
{{/* Images from page bundle */}}
{{ < /gallery >}}
Shortcode Card
Shortcode card untuk menampilkan konten dalam kotak yang menarik:
{{/* layouts/shortcodes/card.html */}}
{{- $title := .Get "title" -}}
{{- $href := .Get "href" | default "" -}}
{{- $image := .Get "image" -}}
{{- $class := .Get "class" | default "" -}}
{{- $style := .Get "style" | default "default" -}}
<div class="card card-{{ $style }} {{ $class }}">
{{- if $image -}}
<div class="card-image">
{{- if $href -}}<a href="{{ $href }}">{{- end -}}
<img src="{{ $image }}" alt="{{ $title }}" loading="lazy">
{{- if $href -}}</a>{{- end -}}
</div>
{{- end -}}
<div class="card-content">
{{- if and $title $href -}}
<h3 class="card-title"><a href="{{ $href }}">{{ $title }}</a></h3>
{{- else if $title -}}
<h3 class="card-title">{{ $title }}</h3>
{{- end -}}
<div class="card-body">
{{ .Inner | .Page.RenderString }}
</div>
</div>
</div>
Shortcode Call to Action
Shortcode CTA untuk menampilkan call-to-action yang eye-catching:
{{/* layouts/shortcodes/cta.html */}}
{{- $text := .Get "text" "Hubungi Kami" -}}
{{- $href := .Get "href" "#" -}}
{{- $style := .Get "style" "primary" -}}
{{- $icon := .Get "icon" "" -}}
<div class="cta cta-{{ $style }}" role="button" tabindex="0" onclick="window.location.href='{{ $href }}'">
<span class="cta-icon">{{ $icon }}</span>
<span class="cta-text">{{ $text }}</span>
<span class="cta-arrow">→</span>
</div>
Shortcode Timeline
Untuk menampilkan konten dalam format timeline:
{{/* layouts/shortcodes/timeline.html */}}
{{- $items := split .Inner "---" -}}
<div class="timeline">
{{- range $index, $item := $items -}}
{{- if $item -}}
{{- $data := split $item "||" -}}
<div class="timeline-item">
<div class="timeline-marker"></div>
<div class="timeline-content">
{{- index $data 0 | .Page.RenderString -}}
</div>
</div>
{{- end -}}
{{- end -}}
</div>
Penggunaan:
{{ < timeline >}}
2023 || **Januari**: Memulai proyek
2023 || **Maret**: Peluncuran beta
2023 || **Juni**: Peluncuran resmi
---
Parameter Shortcode
Shortcodes dapat menerima parameter melalui atribut atau positional parameters. Memahami kedua metode ini penting untuk membuat shortcode yang fleksibel.
Named Parameters
Named parameters diakses dengan .Get "nama":
{{ < alert type="info" icon="ℹ️" title="Informasi" >}}
Konten alert box
{{ < /alert >}}
Positional Parameters
Positional parameters diakses dengan .Get 0, .Get 1, dll:
{{ < youtube UCwtdbaor3VbFMx7Xt2tBX2Q >}}
{{/* Di template shortcode */}}
{{- $id := .Get 0 -}}
Inner Content
.Inner mengakses konten antara opening dan closing tag:
{{ < note >}}
Ini adalah konten dalam note box.
{{ < /note >}}
{{/* Di template */}}
{{ .Inner | .Page.RenderString }}
Tips dan Best Practices
Dalam membuat dan menggunakan shortcodes, ada beberapa tips dan best practices yang perlu diperhatikan untuk mendapatkan hasil yang optimal.
Pertama, selalu sanitasi input dari shortcode untuk mencegah XSS attacks. Gunakan fungsi .Page.RenderString untuk merender markdown di dalam shortcode dengan aman. Kedua, berikan default values untuk parameter opsional menggunakan default function. Ketiga, gunakan logging untuk debugging saat mengembangkan shortcode baru dengan {{ warnf "Message" }}.
Keempat, hindari shortcode yang terlalu kompleks. Jika Anda membutuhkan logika yang rumit, pertimbangkan untuk memindahkan logika ke partials atau layouts. Kelima, dokumentasikan shortcode custom yang Anda buat agar tim dapat dengan mudah menggunakannya.
Troubleshooting Shortcodes
Beberapa masalah umum yang sering dihadapi saat bekerja dengan shortcodes beserta solusinya perlu dipahami untuk mengantisipasi troubleshooting.
Masalah pertama adalah shortcode tidak ter-render dengan benar. Ini biasanya disebabkan oleh syntax error di template shortcode atau konflik dengan markdown parser. Periksa konsol build untuk error messages dan pastikan tidak ada whitespace yang tidak diinginkan di template.
Masalah kedua adalah parameter tidak terbaca. Pastikan menggunakan tanda yang tepat (% atau |) sesuai kebutuhan dan check apakah parameter sudah didefinisikan dengan benar di template.
Masalah ketiga adalah Inner content tidak ter-render sebagai markdown. Jika Anda ingin konten dalam shortcode diparse sebagai markdown, gunakan .Inner | .Page.RenderString alih-alih .Inner saja.
Kesimpulan
Shortcodes adalah fitur yang sangat powerful di Hugo untuk menambahkan konten dinamis ke dalam artikel markdown. Dengan menguasai shortcode bawaan Hugo dan kemampuan membuat shortcode custom, Anda dapat memperkaya konten website tanpa mengorbankan kesederhanaan penulisan markdown. Eksperimen dengan berbagai jenis shortcode dan temukan kombinasi yang paling sesuai dengan kebutuhan website Anda.
Artikel Terkait
Link Postingan : https://www.tirinfo.com/tutorial-hugo-shortcodes/