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.
Tak lengkap jika tidak bisa melakukan pencarian pada sebuah dokumentasi, tentu itu akan mengurangi experience saat membaca dokumentasi tersebut.
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.
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:
- Menjalankan Typesense dengan Docker
- Install Component Search Bar pada Docusaurus
- 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.
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,
},
Lalu diatas themeConfig
tambahkan variable theme seperti gambar dibawah:
themes: ['docusaurus-theme-search-typesense'],
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.
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",
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
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
.
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 😎