Xử lý sự cố thường gặp

5

Tài liệu này tổng hợp các sự cố phổ biến có thể gặp khi sử dụng Init Docs và cách xử lý tương ứng. Nội dung được trình bày theo dạng tra cứu nhanh, không yêu cầu đọc theo thứ tự.

Theme đã kích hoạt nhưng giao diện hiển thị không đúng

Trong trường hợp Init Docs đã được kích hoạt nhưng giao diện hiển thị khác với mong đợi, bạn nên kiểm tra:

  • Theme đã được kích hoạt đúng hay chưa
  • Có theme con hoặc tuỳ biến nào đang ghi đè template
  • Có plugin nào can thiệp mạnh vào frontend

Bạn nên thử tạm thời tắt các plugin không cần thiết để xác định nguyên nhân.

Trang chủ không hiển thị đúng bố cục tài liệu

Init Docs được thiết kế để trang chủ tập trung vào tra cứu, không phải danh sách bài viết.

Nếu trang chủ hiển thị không đúng, bạn nên:

  • Kiểm tra thiết lập hiển thị trang chủ trong WordPress
  • Xem lại nội dung tiêu đề và mô tả trang chủ trong Theme Settings
  • Đảm bảo không dùng template trang chủ khác

Trang chủ nên được giữ đơn giản để phục vụ mục đích tìm kiếm tài liệu.

Demo không hiển thị trong bài viết

Nếu demo không xuất hiện trong bài viết, bạn nên kiểm tra các điểm sau:

  • Tuỳ chọn Post Demo Mode đã được bật trong Theme Settings
  • Bài viết có sử dụng shortcode hay chưa
  • Demo metabox có nội dung HTML hợp lệ

Nếu không có shortcode , nội dung demo sẽ không được render.

CSS hoặc JavaScript của demo không hoạt động

Khi demo hiển thị nhưng hiệu ứng không hoạt động, bạn nên:

  • Kiểm tra lỗi JavaScript trong trình duyệt
  • Đảm bảo code demo không phụ thuộc thư viện ngoài
  • Tránh trùng class hoặc ID với giao diện chính

CSS và JavaScript demo chỉ được nạp cho trang bài viết hiện tại.

Code block không được highlight

Nếu code block không được tô màu cú pháp, bạn nên kiểm tra:

  • Plugin Prismatic đã được cài đặt và kích hoạt
  • Code được đặt trong thẻ pre và code
  • Class ngôn ngữ được khai báo đúng

Init Docs không xử lý syntax highlighting nếu không có plugin hỗ trợ.

Tìm kiếm không trả về kết quả mong muốn

Kết quả tìm kiếm phụ thuộc nhiều vào cấu trúc và cách viết nội dung.

Nếu tìm kiếm không hiệu quả, bạn nên:

  • Kiểm tra lại tiêu đề bài viết
  • Đảm bảo heading mô tả đúng nội dung
  • Không nhồi nhét từ khoá không cần thiết

Cấu trúc nội dung rõ ràng giúp hệ thống tìm kiếm hoạt động tốt hơn.

Website tải chậm khi tài liệu nhiều

Khi số lượng tài liệu tăng, bạn nên chú ý tới hiệu năng:

  • Sử dụng plugin cache phù hợp
  • Giảm plugin không cần thiết
  • Kiểm tra hosting và tài nguyên máy chủ

Init Docs được thiết kế gọn nhẹ, nhưng hiệu năng tổng thể vẫn phụ thuộc vào môi trường.

Xung đột với plugin khác

Một số plugin có thể gây xung đột do can thiệp sâu vào frontend hoặc editor.

Trong trường hợp xảy ra xung đột:

  • Tạm thời tắt plugin nghi ngờ
  • Kiểm tra lại chức năng bị ảnh hưởng
  • Ưu tiên plugin gọn nhẹ, rõ chức năng

Website tài liệu nên hạn chế sử dụng plugin nặng hoặc đa năng quá mức.

Khi nào cần kiểm tra lại cấu trúc tài liệu?

Bạn nên xem xét lại cấu trúc tài liệu nếu:

  • Người đọc khó tìm nội dung
  • Category trở nên quá rộng
  • Bài viết liên quan không còn phù hợp

Việc điều chỉnh sớm giúp tránh phải tái cấu trúc lớn.

Tổng kết

Phần lớn sự cố khi sử dụng Init Docs đến từ cấu hình hoặc nội dung, không phải do theme. Việc nắm rõ cách xử lý các tình huống phổ biến giúp bạn duy trì website tài liệu ổn định, rõ ràng và dễ bảo trì trong thời gian dài.

Bài viết liên quan