Membuat Tag Plugins di Hexo

Pada Hexo dan banyak Static Site Generator lainnya, kita menggunakan Markdown untuk membuat konten. Markdown adalah format yang populer karena kesederhanaannya dalam menulis teks. Namun, seperti yang kita ketahui, Markdown memiliki beberapa keterbatasan dalam hal fleksibilitas dan pengelolaan elemen-elemen kompleks.

Sebagai contoh, secara default, Markdown membungkus elemen gambar dalam tag <p>, yang secara semantik kurang tepat. Markdown juga tidak menyediakan cara langsung untuk menambahkan elemen lain pada gambar, misalnya caption.

Kabar baiknya, Hexo menyediakan solusi untuk mengatasi keterbatasan Markdown, yaitu dengan tag plugins.

Apa Itu Tag Plugins dan Bagaimana Cara Kerjanya?

Tag plugins di Hexo adalah fitur yang memungkinkan Anda untuk menyisipkan elemen-elemen khusus ke dalam konten menggunakan sintaks tag yang sederhana. Jika Anda sudah familiar dengan Hugo dan istilah “shortcodes”, maka tag plugins di Hexo berfungsi dengan cara yang serupa.

Tag plugins bekerja di sisi server, dalam hal ini di local server. Ketika Hexo mendeteksi tag seperti {% tag_name ... %} dalam file Markdown, Hexo akan menjalankan fungsi hexo.extend.tag.register yang telah Anda buat.

Kemudian, saat build time atau ketika perintah hexo generate dijalankan, tag tersebut beserta seluruh konten Markdown akan di-parse menjadi HTML seperti biasa.

Membuat Custom Tag Plugins di Hexo

Hexo sendiri sudah menyediakan built-in tag plugins seperti blockquote, embeded, dan image. Tetapi, bagaimana bila tag plugins bawaan Hexo tidak memenuhi kebutuhan kita? Bisakah kita membuat custom tag plugins? Tentu saja bisa.

Di tutorial ini saya akan mencontohkan membuat 2 jenis tag plugins: inline tag dan block tag.

• Inline tags:

  Tag plugins tanpa end tags. Digunakan untuk membuat tag sederhana yang hanya menerima argumen, misalnya image. Ketika digunakan di Markdown, sintaksnya seperti ini: {% tag_name ... %}.

• Block tags:

  Tag plugins dengan end tags. Digunakan apabila kita ingin membuat elemen yang lebih kompleks. Di dalam tag ini kita dapat memasukkan Markdown, konten yang cukup panjang, bahkan tag plugins lainnya. Sintaks:

  {% tag_name %} 
  .......
  {% endtag_name %}

Step 1: Buat File untuk Plugin

Buat file tag-plugin.js di folder ./themes/theme-anda/scripts. Nama file bebas asalkan masuk akal, yang mandatory hanyalah letak foldernya.

.theme-anda
├── _config.yml
├── languages
├── layout
├── scripts => buat file di sini
└── source

Untuk memudahkan pengelolaan kita dapat mendaftarkan beberapa tag plugin dalam satu file. Ini juga yang membedakan Hugo dan Hexo. Di Hugo, kita hanya bisa memasukkan 1 shortcode dalam 1 file. Bisa sih diakali, tapi memerlukan konfigurasi tambahan.

Step 2: Tulis Kode Plugin

Karena Hexo dibangun di atas Node.js yang notabene JavaScript, cara menulis kodenya hampir sama dengan ketika kita menulis functions di vanilla JS. Ada nama functions, paremeter, dan return untuk mengeksekusi functions tersebut.

1. Inline Tags

   Untuk contoh inline tags, kita akan membuat elemen figure untuk memasukkan image beserta caption-nya.

   Tulis kode berikut di file tag-plugin.js:

   hexo.extend.tag.register('langit_img_caption', function(args) {
     const [url, alt, caption] = args;
     return `
       <figure>
         <img src="${url}" alt="${alt}">
         <figcaption>${caption}</figcaption>
       </figure>
     `;
   });

   Keterangan:

   • hexo.extend.tag.register: metode untuk mendaftarkan tag plugins baru.
   • langit_img_caption: nama tag plugins.
   • args: parameter.

2. Block Tags

   Di contoh kedua, kita akan membuat elemen yang lebih kompleks, yaitu elemen notes.

   hexo.extend.tag.register('langit_note', function(content) {
     const renderedContent = hexo.render.renderSync({text: content, engine: 'markdown'});
     return `
     <div class="hexo-note">
       <span>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-6" width="24" height="24">
           <path fill-rule="evenodd" d="M2.25 12c0-5.385 4.365-9.75 9.75-9.75s9.75 4.365 9.75 9.75-4.365 9.75-9.75 9.75S2.25 17.385 2.25 12Zm8.706-1.442c1.146-.573 2.437.463 2.126 1.706l-.709 2.836.042-.02a.75.75 0 0 1 .67 1.34l-.04.022c-1.147.573-2.438-.463-2.127-1.706l.71-2.836-.042.02a.75.75 0 1 1-.671-1.34l.041-.022ZM12 9a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Z" clip-rule="evenodd" />
         </svg>
         Notes:
       </span>
       ${renderedContent}
     </div>
     `;
   }, { ends: true });

Perhatikan bahwa saya menggunakan nama langit_img_caption, nama “langit” digunakan sebagai unique identifier untuk membedakan antara custom tag plugin yang saya buat dengan tag plugin bawaan Hexo. Mirip dengan text domain di template WordPress.

Nama tag plugins bebas, tetapi ada beberapa aturan penulisan:

• Nama harus unik dan deskriptif untuk mencegah konflik dengan built-in tag plugins.
• Ditulis dalam huruf kecil semua.
• Bila terdiri dari dua kata atau lebih, gunakan garis bawah (_) untuk memisahkan antarkata. Mengikuti konvensi penamaan di JavaScript.

Anda juga dapat menambahkan class pada elemen HTML agar tampilannya dapat diatur di CSS. Bila Anda menggunakan Tailwind CSS seperti saya, class Tailwind dapat ditambahkan langsung di elemen tersebut. Tapi, pastikan bahwa konfigurasi di tailwind.config.js juga mencakup file .js dan .ejs.

Namun, perlu diingat bahwa setiap perubahan yang dilakukan di tag plugin maka kita harus melakukan build ulang. Jadi, saya pribadi lebih merekomendasikan menggunakan vanilla CSS alih-alih langsung menggunakan class Tailwind.

Step 3: Buat User Snippet (Opsional)

Step ketiga ini opsional. Anda bisa menggunakan user snippet atau tidak. Tetapi, untuk hidup yang lebih selow, saya menyarankan Anda membuat user snippet untuk masing-masing tag plugin.

Karena tutorial ini sudah terlalu panjang, saya tidak akan membahas caranya di sini. Untuk Anda yang belum familiar dengan cara membuat user snippet, bisa membacanya di artikel “Tutorial Membuat User Snippet di Visual Studio Code”.

Step 4: Gunakan Tag Plugins di Konten

Sekarang, Anda dapat menggunakan tag plugin di Markdown.

{% langit_img_caption "https://example.com/image.jpg" "Contoh Gambar" "Ini adalah caption untuk gambar." %}

Output:

Untuk block tag plugin:

{% langit_note %}

<!-- Kita bisa menulis markdown seperti biasa di sini -->

{% endlangit_note %}

Output:

Step 5: Clean and Generate

Setelah selesai menambahkan custom tag plugins, jalankan perintah berikut di terminal agar Hexo membersihkan cache dan men-generate ulang semua file.

hexo clean
hexo generate

Kemudian jalankan kembali server untuk memeriksa apakah tag plugins yang Anda buat telah sesuai dengan kebutuhan atau belum. Bila semua sudah oke, Anda bisa men-deploy ke production.

Mengapa Menggunakan Tag Plugins? Mengapa Tidak Langsung HTML Saja?

Barangkali pertanyaan ini sempat tebersit di benak Anda, mengapa kita harus repot-repot membuat tag plugins? Mengapa tidak langsung menggunakan tag HTML di Markdown?

Well, ada beberapa alasan mengapa kita tidak melakukan itu:

1. Kehilangan kesederhanaan Markdown

   Tujuan menulis konten dengan Markdown sendiri adalah agar proses penulisan menjadi lebih sederhana. Jika kita banyak menggunakan tag HTML langsung, kita kehilangan kesederhanaan itu.

   Contoh penulisan dengan Markdown:

   <!-- Contoh penulisan list dengan Markdown -->
   1. Daftar nomor pertama.
   2. Daftar nomor kedua.
   3. Daftar nomor ketiga.

   Sekarang bandingkan dengan menggunakan HTML:

   <!-- Contoh penulisan list dengan HTML -->
   <ol>
     <li>Daftar nomor pertama.</li>
     <li>Daftar nomor kedua.</li>
     <li>Daftar nomor ketiga.</li>
   </ol>

2. Masalah portabilitas

   Tidak semua parser Markdown mendukung HTML dengan cara yang sama. Ini dapat menyebabkan hasil yang tidak konsisten saat dokumen dibuka di berbagai alat atau platform.

3. Kompatibilitas

   Beberapa alat Markdown mungkin memblokir atau membatasi penggunaan HTML karena alasan keamanan, terutama untuk dokumen yang diproses di web (misalnya, GitHub Pages mungkin memfilter elemen tertentu untuk mencegah serangan XSS).

4. Sulit dipelihara

   Dokumen yang dicampur antara Markdown dan HTML bisa menjadi lebih sulit dirawat, terutama jika tim yang mengelola dokumen tidak memiliki pemahaman yang mendalam tentang HTML.

5. Mengakses data atau variabel

   Bila langsung menggunakan HTML, kita tidak dapat mengakses data atau locals variable.

Berapa banyak tag plugins yang bisa kita buat?

Sebanyak yang kita butuhkan. Akan tetapi, meskipun tag plugins berfungsi dengan baik di server lokal, terlalu banyak tag plugins dapat menyulitkan pengelolaan dan memengaruhi kinerja web. Berdasarkan pengalaman saya sebagai seorang bloger yang banyak maunya, saya menggunakan sekitar 25 tag plugins untuk memenuhi kebutuhan konten saya.

Kesimpulannya, buatlah tag plugins secukupnya dan sesuai kebutuhan, agar pengelolaannya tetap efisien tanpa membebani proses build atau kinerja situs Anda. (eL)