Thiết lập giao diện ban đầu

1. Để bắt đầu, trước tiên hãy cài đặt tất cả các gói cần thiết bằng npm install hoặc pnpm install, sau đó chạy một bản build đầu tiên để chắc chắn rằng thiết lập hoạt động, bằng npm run build hoặc pnpm build.
2. Sao chép bản build Pagefind (dùng cho tìm kiếm trên site) để môi trường dev có thể dùng được. Việc này khác nhau tùy theo hệ điều hành của bạn. Tôi đã tạo sẵn một vài lệnh để hỗ trợ.
   • Trên Windows, chạy npm run winsearch
   • Trên OSX hoặc Linux, chạy npm run osxsearch
3. Tiếp theo, bạn sẽ muốn cấu hình thiết lập i18n cho site của mình (một ngôn ngữ, hoặc nhiều ngôn ngữ). Chỉ cần chạy lệnh npm run docs:config-i18n và làm theo hướng dẫn của script là xong!
4. Bây giờ bạn có thể thiết lập site theo ý mình!

Giới thiệu mã nguồn

Tôi đã tạo một vài code tour để giúp bạn làm quen với codebase. Bạn sẽ cần tiện ích mở rộng Code Tour để xem chúng trong VSCode hoặc một IDE khác.

Cấu trúc mã nguồn

Mã nguồn được tổ chức với phần lớn các thành phần nằm trong thư mục src/docs. Điều này giúp bạn dễ dàng thả nguyên thư mục đó vào một dự án sẵn có và bổ sung chức năng tài liệu chỉ trong vài phút.

Tùy chọn cấu hình

Cấu hình chung của site được thực hiện trong thư mục src/docs/config/. Phần lớn cài đặt nằm trong các thư mục ngôn ngữ riêng biệt để việc xử lý bản dịch dễ dàng hơn.

Cài đặt site

Tệp src/docs/config/siteSettings.json.ts được dùng để cấu hình cài đặt của site. Những cài đặt này bao gồm các mục như bật view transitions hay không, bật hiệu ứng động hay không, và có hiển thị nút sao chép liên kết cho các tiêu đề trong tài liệu hay không.

Dữ liệu site

Tệp src/docs/config/[language]/siteData.json.ts được dùng để cấu hình dữ liệu của site. Phần này bao gồm các mục như tiêu đề site, mô tả, liên kết mạng xã hội và ảnh mặc định.

Dữ liệu điều hướng

Cấu hình dữ liệu điều hướng cho thanh navbar trên cùng trong tệp src/docs/config/[language]/navData.json.ts.

Bố cục sidebar

Cấu hình thứ tự các mục tài liệu của bạn trong tệp src/docs/config/[language]/sidebarNavData.json.ts.

Robots

Để các robot như Google nhìn thấy đúng sitemap, bạn sẽ muốn sửa tệp public/robots.txt để dùng tên miền website của mình.

Tài nguyên khác

Thông tin chung về Astro

Astro tìm các tệp .astro hoặc .md trong thư mục src/pages/. Mỗi trang được đưa ra thành một route dựa trên tên tệp của nó.

Thư mục src/components/ không có gì đặc biệt, nhưng đó là nơi chúng tôi thích đặt các component Astro/React/Vue/Svelte/Preact.

Mọi tài nguyên tĩnh, chẳng hạn như hình ảnh, có thể được đặt trong thư mục public/. Tôi cũng thường dùng src/assets cho hình ảnh khi sử dụng Astro assets để tối ưu hóa ảnh.

Lệnh

Tất cả các lệnh đều được chạy từ thư mục gốc của dự án, trong một terminal:

Lệnh	Tác dụng
npm install	Cài đặt các phụ thuộc
npm run dev	Khởi động server dev cục bộ tại localhost:4321
npm run build	Build site production vào ./dist/
npm run preview	Xem trước bản build cục bộ, trước khi triển khai
npm run astro ...	Chạy các lệnh CLI như astro add, astro check
npm run astro -- --help	Xem trợ giúp khi dùng Astro CLI

Muốn tìm hiểu thêm?

Bạn có thể xem tài liệu hoặc tham gia máy chủ Discord.