Menulis Dokumentasi dengan Docusaurus — Part 2: Searching dengan Typesense

Pada artikel sebelumnya, kita telah membahas bagaimana cara menginstall docusaurus berserta cara penggunaannya. Lalu kali ini kita akan melanjutkan pembahasan artikel tersebut.

Menulis Dokumentasi dengan Docusaurus — Part 1: Cara Install dan Penggunaan

Tak lengkap jika tidak bisa melakukan pencarian pada sebuah dokumentasi, tentu itu akan mengurangi experience saat membaca dokumentasi tersebut.

Photo by Damian Zaleski on Unsplash

Layaknya dokumentasi software besar seperti Laravel, TailwindCSS, bahkan Ethereum, kali ini kita akan memberikan fitur yang sama pada dokumentasi yang telah kita buat, yaitu menambahkan fitur Searching.

Searching pada dokumentasi Laravel

Thanks to Docusaurus dengan ribuan fiturnya, kita dapat menambah fitur searching pada dokumentasi kita dengan berbagai cara, contohnya dengan integrasi ke Algolia, Typesense, dan Local Search.

Namun pada artikel kali ini, kita akan mencoba mengintegrasikan docusaurus dengan Typesense. Selain karna typesense bisa dijalankan disistem operasi kita atau self-host, typesense juga dapat diintegrasikan dengan mudah.

Typesense is a modern, privacy-friendly, open source search engine meticulously engineered for performance & ease-of-use.

Sama halnya dengan Elasticsearch, Typesense adalah sebuah database yang dikhususnya untuk melakukan pencarian, namun lebih ringan dan tidak membutuhkan resource yang besar.

Code never lies, comments sometimes do.

Integrasi Docusaurus dengan Typesense

Sebelum memulai proses integrasi, pastikan dokumentasi kita sudah memiliki konten yang cukup, sehingga kita tidak sia-sia untuk menambah fitur search. Lalu persiapkan hal-hal dibawah ini juga:

• Docker, Install di Windows, Linux, atau Mac
• Install JQ
• Jalankan Docusaurus yang sudah diinstall sebelumnya

npm start

Secara umum, kita akan melewati beberapa tahap untuk melakukan peng-integrasian dengan Typesense:

1. Menjalankan Typesense dengan Docker
2. Install Component Search Bar pada Docusaurus
3. Scrape dan Index Data ke Typesense

Setelah itu, fitur search siap untuk digunakan.

Menjalankan Typesense dengan Docker

Sebenarnya, kita tidak diharuskan menggunakan Docker untuk menjalankan typesense, kita bisa langsung meng-install typesense pada operating sistem kita.

Namun kali ini kita akan menggunakan docker karna lebih mudah untuk dijalankan dengan hanya beberapa step.

Jalankan perintah dibawah untuk menjalankan typesense.

docker run -p 8108:8108 \
            -v typesense-data:/data typesense/typesense:0.25.1 \
            --data-dir /data \
            --api-key=APIKEY_KITA_666 \
            --enable-cors

Jika container pada docker sudah berjalan seperti gambar dibawah, artinya typesense siap menerima data hasil scrape kita nanti.

Container Typesense pada Docker Desktop

Install Component Search Bar pada Docusaurus

Component search bar ini disediakan oleh official Docusaurus dan siap untuk kita integrasi ke situs dokumentasi kita.

Jalankan perintah berikut di directory docusaurus kita untuk mengunduh dependensi search bar pada situs dokumentasi kita.

npm install docusaurus-theme-search-typesense@next --save

Lalu tambahkan configurasi typesense pada docusaurus.config.js, masukkan configurasi dibawah pada variabel themeConfig seperti pada gambar dibawah:

typesense: {
  // Replace this with the name of your index/collection.
  // It should match the "index_name" entry in the scraper's "config.json" file.
  typesenseCollectionName: "docusaurus-2",

  typesenseServerConfig: {
    nodes: [
      {
        host: "localhost",
        port: 8108,
        protocol: "http",
      },
    ],
    apiKey: "APIKEY_KITA_666",
  },

  // Optional: Typesense search parameters: https://typesense.org/docs/0.24.0/api/search.html#search-parameters
  typesenseSearchParameters: {},

  // Optional
  contextualSearch: true,
},

docusaurus.config.js

Lalu diatas themeConfig tambahkan variable theme seperti gambar dibawah:

themes: ['docusaurus-theme-search-typesense'],

themes pada docusaurus.config.js

Ini berfungsi untuk menampilkan component search bar yang sudah kita tambahkan sebelumnya.

Setelah proses ini dijalankan dengan benar, maka search bar akan muncul dipojok kanan atas, namun belum bisa digunakan untuk melakukan pencarian, baru setelah tahap terakhir nanti dapat digunakan sebagai mestinya.

Search bar di Docusaurus

Tips:

Jika belum muncul meski sudah melakukan step yang sama persis, silahkan restart docusaurus dengan menghentikan command npm start dan menjalankan ulang command tersebut.

Persiapan Sebelum Scrape dan Index Data ke Typesense

Sebelum kita menjalankan scrape data, kita perlu menyiapkan agar situs dokumentasi kita bisa discrape.

Langkah pertama adalah dengan mengubah configurasi url pada docusaurus.config.js menjadi seperti dibawah.

url: "http://host.docker.internal:3000",

Url pada docusaurus.config.js

Selanjutnya, hentikan semua command npm start yang telah kita jalankan sebelumnya, karna setelah ini kita akan melakukan proses building.

• Hentikan semua command npm start yang sedang kita jalankan
• Jalankan perintah dibawah

npm run build

npm run serve

Penampakan proses building docusaurus

Jika sudah keluar message seperti dibawah, berarti docusaurus sudah berhasil di jalankan dan siap untuk di-scrape.

Langkah selanjutnya dan terakhir adalah proses scrape dan indexing data.

Scrape dan Index Data ke Typesense

Langkah pertama, buatlah dua file pada directory my-documentation yang kita buat sebelumnya, yaitu .env dan config.json.

Directory my-documentation

Pada file .env isi sebagai berikut:

TYPESENSE_API_KEY=APIKEY_KITA_666
TYPESENSE_HOST=host.docker.internal
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http

Lalu untuk config.json isi sebagai berikut:

{
  "index_name": "docusaurus-2",
  "start_urls": [],
  "sitemap_urls": [
    "http://host.docker.internal:3000/sitemap.xml"
  ],
  "sitemap_alternate_links": true,
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
      "type": "xpath",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "header h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5, article td:first-child",
    "lvl6": "article h6",
    "text": "article p, article li, article td:last-child"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": [
      "language",
      "version",
      "type",
      "docusaurus_tag"
    ],
    "attributesToRetrieve": [
      "hierarchy",
      "content",
      "anchor",
      "url",
      "url_without_anchor",
      "type"
    ]
  },
  "conversation_id": [
    "833762294"
  ],
  "nb_hits": 46250
}

Setelah file selesai dibuat, saatnya menjalakan proses scraping dan indexing.

Jalankan perintah berikut pada folder my-documentation

docker run -it --env-file=.env -e "CONFIG=$(cat config.json | jq -r tostring)" typesense/docsearch-scraper:0.9.1

Jika berakhir dengan nilai Nb Hits tidak 0, maka proses scrape berhasil.

Selanjutnya kita bisa mencoba fitur search, dan taraaa!

Selamat! Situs dokumentasi kita sudah terintegrasi dengan Typesense dan sudah bisa melakukan pencarian seperti React Docs 😎

Referensi

Typesense Documentation

Search | Docusaurus