Tutorial Membuat Daftar Isi di Hugo

Cara membuat daftar isi di Hugo sebetulnya cukup sederhana karena Hugo sendiri dilengkapi dengan fitur table of content (TOC) . Sayangnya, kurang fleksibel jika digunakan di dalam artikel.

Maksud saya, pembuatan table of content yang mereka sarankan adalah membuat template partial, lalu memasukkannya di <aside>. Bisa di bawah atau di atas artikel. Ini jelas bukan letak yang kita inginkan karena daftar isi biasanya diletakkan di dalam artikel.

Cara Membuat Daftar Isi untuk Artikel di Hugo

Goal-nya adalah membuat daftar isi yang bisa diletakkan di mana saja di dalam artikel. Tidak otomatis karena tidak setiap artikel memerlukan daftar isi.

Kita akan tetap menggunakan automatically parse Markdown content bawaan Hugo, tetapi dengan sedikit modifikasi.

Step 1: Atur Daftar Isi di Config.toml

Buka file config.toml dan tambahkan sintaks berikut ini. Jika sebelumnya sudah ada pengaturan lain untuk [markup], maka sintaks [markup] di bawah bisa dihapus, copy dari mulai [markup.tableOfContents].

[markup]
  [markup.tableOfContents]
    endLevel   = 3
    ordered    = false
    startLevel = 2

Keterangan

• endLevel ==> sampai di heading level berapa TOC akan dibuat. Tipe string. Misalnya kalau kita ingin yang masuk ke daftar isi sampai h4, maka isikan 4. Jika sampai h3 atau heading level 3, maka isikan 3.
• ordered ==> Tipe boolean, default false. True untuk numbering atau ol, false jika ingin menggunakan bulleting atau ul.
• startlevel ==> mulai di heading level berapa. Isi hanya angka. Misal, 1 untuk <h1>, 2 untuk <h2>, dan seterusnya. Sebagai catatan, hindari menggunakan startlevel 1 karena <h2> hanya untuk judul artikel yang notabene tidak masuk ke daftar isi.

Anda yang terbiasa menggunakan WordPress, pasti agak misuh-misuh karena kalau di WP, kita bisa mengatur heading level yang akan dimasukkan ke daftar isi untuk setiap artikel. Misalnya, untuk artikel A, daftar isinya hanya <h2>, untuk artikel B daftar isinya sampai <h4>, dan seterusnya.

Sayangnya, di Hugo saya tidak menemukan cara untuk membuatnya seperti itu. So, pengaturan heading level ini berlaku global alias untuk setiap artikel.

Step 2: Buat Shortcode untuk TOC

Langkah untuk membuat daftar isi otomatis di Hugo berikutnya adalah membuat shortcodes. Buat file shortcodes baru di:

layouts/
├── _default/
├── partials/
└── shortcodes/
    └── toc.html <- buat file di sini

Nama file bebas, di tutorial ini saya menggunakan nama file “toc.html”. Di file tersebut, masukkan sintaks {{ .Page.TableOfContents }}. Tetapi, karena untuk keperluan styling nantinya, kita akan membungkus daftar isi tersebut dengan <div> dan diberi <class>:

<!-- toc.html -->
<div class="toc">
    <button id="tocButton" type="button" class="toc__button"> DAFTAR ISI </button>
    <div id="tocContent" class="toc__content" aria-labelledby="toc__button">
        {{ .Page.TableOfContents }}
    </div>
</div>

Nama class di div bebas. Perhatikan juga bahwa saya menambahkan tombol dan memberinya ID. Ini akan kita gunakan untuk membuat collapsible table of content.

Step 3: Masukkan ke Dalam Artikel

Untuk memasukkan TOC ke dalam artikel, kita cukup memanggil shortcodes tersebut seperti ini:

{{ <toc> }}

Letakkan di mana pun di dalam artikel. Tampilannya seperti artikel di tutorial ini. Jika Anda kurang suka dengan tampilannya, silakan atur dengan CSS atau beri class yang sesuai dengan CSS framework yang Anda gunakan.

Daftar isi di Hugo akan di-render sebagai <nav> dan ul seperti berikut.

<div class="toc">
    <button id="tocButton" type="button" class="toc__button"> DAFTAR ISI </button>
    <div id="tocContent" class="toc__content show" aria-labelledby="toc__button">
        <nav id="TableOfContents">
  <ul>
    <li><a href="#cara-membuat-daftar-isi-untuk-artikel-di-hugo">Cara Membuat Daftar Isi untuk Artikel di Hugo</a>
      <ul>
        <li><a href="#step-1-atur-daftar-isi-di-configtoml">Step 1: Atur Daftar Isi di Config.toml</a></li>
        <li><a href="#step-2-buat-shortcode-untuk-toc">Step 2: Buat Shortcode untuk TOC</a></li>
        <li><a href="#step-3-masukkan-ke-dalam-artikel">Step 3: Masukkan ke Dalam Artikel</a></li>
      </ul>
    </li>
    <li><a href="#bonus-cara-membuat-collapsible-toc">Bonus: Cara Membuat Collapsible TOC</a>
      <ul>
        <li><a href="#membuat-collapsible-table-of-content-dengan-javascript">Membuat Collapsible Table of Content dengan Javascript</a></li>
        <li><a href="#membuat-collapsible-table-of-content-dengan-bootstrap">Membuat Collapsible Table of Content dengan Bootstrap</a></li>
      </ul>
    </li>
  </ul>
</nav>
    </div>
</div>

Di tutorial kali ini saya tidak akan memberikan sintaks CSS-nya karena jika sudah sampai sini, saya berasumsi Anda sudah paham CSS . Lagipula, tampilan setiap blog pasti berbeda.

Bonus: Cara Membuat Collapsible TOC

Bagaimana kalau kita mau membuat daftar isi collapsible yang bisa tertutup atau terbuka ketika diklik? Ada dua cara untuk membuatnya: menggunakan komponen accordion di Bootstrap atau menggunakan vanilla JavaScript.

Membuat Collapsible Table of Content dengan Javascript

Ada tiga hal yang akan kita lakukan di sini: memodifikasi sintaks di shortcode TOC, CSS, dan Javascript.

1. Modifikasi Sintaks di Shortcode

Tetapi sebelumnya, kita modifikasi dulu

<script>
    document.addEventListener("DOMContentLoaded", function () {
        const judulItems = document.querySelectorAll(".toc__button");

        judulItems.forEach(function (judulItem) {
            judulItem.addEventListener("click", function () {
                const subDaftarIsi = document.getElementById("tocContent");

                if (subDaftarIsi.classList.contains("show")) {
                    subDaftarIsi.classList.remove("show");
                } else {
                    subDaftarIsi.classList.add("show");
                }
            });
        });
    });

</script>

Membuat Collapsible Table of Content dengan Bootstrap

Bila Anda menggunakan Bootstrap , caranya lebih mudah karena Bootstrap sendiri sudah dilengkapi dengan komponen accordion. Ya, sebetulnya sama-sama menggunakan JS, tapi JavaScript-nya sudah dibuatkan oleh Bootstrap.

<div class="toc">
    <button type="button" class="toc__button-contoh" data-bs-toggle="collapse" data-bs-target="#contoh"> DAFTAR
        ISI {{ partial "content/svg.html" (dict "svg" "menuBurger") }}</button>
    <div id="contoh" class="collapse show" aria-labelledby="toc__button">
        {{ .Page.TableOfContents }}
    </div>

</div>