Tìm Kiếm Tĩnh Cho Static Site Với Astro + Pagefind

Static site có nhiều ưu điểm — nhanh, an toàn, rẻ — nhưng thiếu một thứ quan trọng: tìm kiếm. Không có server đồng nghĩa không có database để query. Pagefind giải quyết vấn đề này bằng cách index toàn bộ nội dung ngay tại build time, tạo ra một search index tĩnh hoạt động hoàn toàn trên trình duyệt.

Pagefind Là Gì?#

Pagefind là công cụ tìm kiếm tĩnh, zero-config, chạy sau khi build. Nó quét thư mục output HTML, phân tích nội dung, và sinh ra search index dưới dạng file tĩnh. Kết quả: người dùng có thể tìm kiếm toàn bộ site mà không cần server, database, hay API bên thứ ba.

Đặc điểm chính:

• Tự động — không cần cấu hình, tự động phát hiện nội dung
• Không server — index là file tĩnh, search chạy hoàn toàn trên client
• UI tích hợp — component searchbox sẵn dùng
• Đa ngôn ngữ — hỗ trợ segmentation cho nhiều ngôn ngữ
• Phân trang, filter, sorting có sẵn

astro-pagefind — Astro Integration#

astro-pagefind là integration chính thức cho Astro, giúp tích hợp Pagefind vào build pipeline chỉ với vài dòng config:

npm i astro-pagefind

import { defineConfig } from 'astro/config'
import pagefind from 'astro-pagefind'

export default defineConfig({
  integrations: [pagefind()],
})

Sau mỗi lần astro build, Pagefind tự động index toàn bộ output HTML và sinh search index tại _pagefind/.

Hai Cách Dùng UI#

1. Component Searchbox (classic)#

---
import Search from 'astro-pagefind/components/Search.astro'
---

<Search
  instance="search"
  className="pagefind-ui"
  searchboxOptions={{ placeholder: 'Tìm kiếm...' }}
/>

2. Pagefind UI Component (khuyên dùng từ v1.5.0)#

---
import PagefindConfig from 'astro-pagefind/components/PagefindConfig.astro'
---

<PagefindConfig />
<pagefind-searchbox></pagefind-searchbox>

Cách này dùng Web Component của Pagefind, dễ custom hơn và không cần bảo trì UI riêng.

Cách Blog Này Dùng Pagefind#

Blog này dùng astro-pure theme, tích hợp Pagefind sẵn qua config:

// src/site.config.ts
prerender: true,
integ: {
  pagefind: true,
}

Component search ở /search dùng Pagefind UI với custom CSS variables để match theme màu của blog:

--pagefind-ui-primary: hsl(var(--primary));
--pagefind-ui-text: hsl(var(--foreground));
--pagefind-ui-background: hsl(var(--muted));

Tags trên bài viết cũng được đánh dấu để Pagefind filter:

data-pagefind-filter='tag'

So Sánh Với Giải Pháp Khác#

Hoạt Động Dưới Hood#

Khi chạy astro build, quy trình diễn ra như sau:

1. Astro build toàn bộ site ra HTML tĩnh
2. Pagefind quét thư mục output
3. Phân tích nội dung từng trang (title, headings, paragraph, meta)
4. Tách từ, loại bỏ stop words
5. Xây dựng inverted index
6. Ghi index ra file JSON tĩnh trong _pagefind/

Khi người dùng gõ từ khoá:

1. Trình duyệt tải index JSON (~100-500KB tuỳ dung lượng site)
2. Pagefind thực hiện search hoàn toàn trên client
3. Hiển thị kết quả với highlight matching text
4. Tất cả diễn ra trong milliseconds — không network request

Ưu Nhược Điểm#

Ưu:

• Dễ tích hợp — thêm 1 dòng config là xong
• Không chi phí vận hành — không server, không API key
• Tốc độ nhanh — index client-side, không latency network
• Riêng tư — không gửi dữ liệu search ra ngoài
• Hỗ trợ view transitions — giữ search state khi chuyển trang

Nhược:

• Index phải tải về trình duyệt — site lớn có thể nặng
• Không real-time — muốn cập nhật nội dung phải build lại
• Tìm kiếm fuzzy cơ bản — không mạnh bằng Elasticsearch
• Không phân quyền — index public, mọi người đều search được

Kết Luận#

Nếu bạn xây static site với Astro và cần tính năng tìm kiếm, Pagefind là giải pháp tối ưu. Không server, không chi phí, cài đặt trong 5 phút — phù hợp cho blog, tài liệu, knowledge base.

Blog này là một ví dụ: trang search hoạt động hoàn toàn không cần backend, mọi từ khoá được xử lý ngay trên trình duyệt của bạn.

Tài liệu tham khảo#

• Pagefind Official Documentation ↗
• astro-pagefind Integration ↗
• Astro Official Documentation ↗
• Pagefind — GitHub Repository ↗