Hướng dẫn sử dụng các tính năng mới: Ghi Chú Tác Giả, Shortcode Blog và Thử Thách Đọc Truyện

1. Ghi chú tác giả cuối chương (Creator’s Thoughts)

Tính năng này cho phép tác giả hoặc nhóm dịch thêm lời nhắn cuối mỗi chương truyện, nhằm chia sẻ cảm xúc, thông tin hậu trường hoặc gửi lời cảm ơn đến độc giả.

Cách sử dụng

• Trong nội dung chương, thêm một dòng bắt đầu bằng dấu ///, ví dụ: /// Cảm ơn các bạn đã đọc!.
• Hệ thống sẽ tự động tách dòng này và hiển thị trong một thẻ UIkit card riêng bên dưới nội dung chương.

Ưu tiên hiển thị thông tin

• Nếu bật Author Mode, hệ thống lấy tên tác giả chương truyện.
• Nếu truyện có nhóm dịch, hiển thị thông tin nhóm thay thế.
• Nếu không có hai điều kiện trên, sử dụng taxonomy author làm fallback.

Khối ghi chú sẽ hiển thị avatar, tên người đăng, vai trò (tác giả/nhóm dịch) và nội dung được định dạng tự động.

2. Ảnh bìa chương thủ công (Manual Chapter Cover)

Mặc định hệ thống sẽ tự động chọn ảnh bìa từ chương (thường hoạt động tốt với truyện có kích thước trang chuẩn). Tuy nhiên, với webtoon có ảnh dài, việc auto-detect có thể chọn nhầm ảnh credit.

Cách sử dụng

• Trong nội dung chương, thêm một dòng ở cuối chương với cú pháp: |||<img src="URL-ảnh-bìa">.
• Ví dụ: |||<img src="http://domain.com/path/cover.webp">.
• Nên đặt ở cuối chương để tránh tính năng preload chọn sai ảnh.

Lưu ý

• Chỉ sử dụng khi cần override auto-detect mặc định.
• Đảm bảo URL ảnh hợp lệ và đã được upload vào thư viện.

3. Shortcode bài viết

Các shortcode dưới đây khớp 100% với code hiện tại. Hầu hết hỗ trợ định danh truyện bằng id | slug | title (ghi rõ từng cái). Nếu không tìm thấy dữ liệu, shortcode trả về HTML rỗng (có thể override bằng tham số empty, filter init_manga_empty_html). Tham số được kiểm tra hợp lệ: whitelist cho style/layout/size; giới hạn số cho columns/limit.

3.1 [manga_info]

• Chức năng: Card truyện: ảnh bìa (hỗ trợ che mờ + nút hiện ảnh), tiêu đề, mô tả ngắn, lượt xem, số chương, badge 18+, trạng thái (check “Completed”).
• Cú pháp: [manga_info id="123" show_all_genres="true" empty=""] (cũng nhận slug | title).
• Tham số:
  • show_all_genres: true để hiển thị tối đa 3 thể loại; mặc định chỉ 1.
  • empty: HTML thay thế khi không có truyện.
• Lưu ý: Thumbnail size đổi qua filter init_manga_card_thumb_size. Trạng thái map sẵn: completed/ongoing/dropped/hiatus. Chuẩn hoá tuổi: 18+ với các biến thể (adult, r18, nsfw…).

3.2 [manga_details]

• Chức năng: Danh sách chi tiết: tên khác, số chương (có pluralization), tình trạng, tác giả (Author Mode hoặc author_tax), nhóm dịch, thể loại.
• Cú pháp: [manga_details slug="ten-truyen" empty=""] (cũng nhận id | title).
• Tham số: chỉ có empty. Không có fields/layout.

3.3 [manga_stats]

• Chức năng: Thống kê nhanh: lượt xem, theo dõi (bookmark), điểm đánh giá (+số lượt), số bình luận. Cache 1 giờ.
• Cú pháp: [manga_stats id="123" style="inline" empty=""] (cũng nhận slug | title).
• Tham số:
  • style: inline | cards | badges
  • empty: HTML thay thế khi không có truyện.
• Lưu ý: Có filter init_manga_stats_output để sửa HTML trả về.

3.4 [manga_read_button]

• Chức năng: Nút “Read” dẫn đến permalink truyện.
• Cú pháp: [manga_read_button id="123" text="" style="primary" size="" class="" empty=""] (cũng nhận slug | title).
• Tham số:
  • text: nhãn nút (mặc định: Read %manga_title%, dịch qua i18n).
  • style: tên style của UIkit (vd: primary, secondary…).
  • size: small | large | rỗng (mặc định).
  • class: thêm class CSS.
  • empty: HTML thay thế khi không có truyện.

3.5 [manga_list]

• Chức năng: Hiển thị danh sách/lưới/carousel truyện theo ID hoặc slug. Tối ưu query, dùng template part.
• Cú pháp: [manga_list ids="123,456,789" layout="grid" columns="3" limit="9" show_chapters="false" show_stats="false" empty=""]
• Tham số:
  • ids hoặc slugs: chọn một kiểu định danh.
  • layout: grid | list | carousel
  • columns: 1–6 (chỉ áp dụng cho grid).
  • limit: 1–50.
  • show_chapters: true/false (nếu có init_manga_get_chapters).
  • show_stats: true/false (bật hiển thị view/… trong item template).
  • empty: HTML thay thế khi không có dữ liệu.
• Lưu ý: no_found_rows, bật cache meta/tax. Tuỳ biến query qua init_manga_list_query_args. Grid/carousel dùng template-parts/manga/item-grid.

3.6 [manga_team]

• Chức năng: Hiển thị nhóm dịch. Hỗ trợ lấy trực tiếp theo team hoặc lấy từ truyện.
• Cú pháp:
  [manga_team id="123" style="card" show_social="true" show_stats="true" empty=""]
  hoặc [manga_team team_id="45"] (cũng nhận slug | title cho truyện).
• Tham số:
  • team_id: ID term của team (nếu truyền, bỏ qua truyện).
  • style: card | badge | inline (mặc định card).
  • show_social: true/false (hiển thị liên kết social có trong term meta).
  • show_stats: true/false (số manga, thành viên, “Since …”).
  • empty: HTML thay thế khi không có dữ liệu.

3.7 [manga_compare]

• Chức năng: So sánh đúng 2 truyện với bộ trường cố định: tình trạng, số chương, điểm, lượt xem, thể loại, tác giả + 2 nút CTA.
• Cú pháp: [manga_compare ids="123,456" empty=""]
• Quy tắc: Bắt buộc chính xác 2 ID hợp lệ. Không hỗ trợ slugs hay các tham số fields/layout/highlight.

3.8 [manga_highlight]

• Chức năng: Khối trích dẫn/nổi bật cho truyện; lấy từ text hoặc fallback sang excerpt/nội dung.
• Cú pháp: [manga_highlight id="123" chapter="12" text="" style="quote" empty=""] (cũng nhận slug | title).
• Tham số:
  • style: quote | card | banner
  • chapter: hiển thị nhãn “Chapter N” (tuỳ chọn).
  • text: nội dung tuỳ chỉnh; rỗng thì dùng excerpt/nội dung rút gọn.
  • empty: HTML thay thế khi không có nội dung.

3.9 [team_manga]

• Chức năng: Liệt kê manga của một nhóm dịch cụ thể.
• Cú pháp: [team_manga team_id="45" limit="6" layout="grid" columns="3" show_chapters="false" show_stats="false" empty=""] (cũng nhận team_slug).
• Tham số:
  • team_id | team_slug: bắt buộc một trong hai.
  • layout: grid | list
  • columns: 1–6 (áp dụng cho grid).
  • limit: 1–50.
  • show_chapters, show_stats: true/false.
  • empty: HTML thay thế khi không có dữ liệu.
• Lưu ý: Tuỳ biến query qua init_team_manga_query_args. Dùng template part đồng bộ với [manga_list].

3.10 Ghi chú

• Cache thống kê trong object cache 1 giờ (group init_manga), key theo manga_stats_{id}.
• Kiểm tra giá trị hợp lệ:
  • style whitelist: inline, cards, badge, badges, card, quote, banner, grid, list, carousel
  • layout whitelist: grid, list, carousel
  • size whitelist: rỗng, small, large
  • columns: clamp 1–6; limit: clamp 1–50.
• Query đã tối ưu (no_found_rows, bật meta/tax cache). Item hiển thị thống nhất qua template-parts/manga/item-grid.
• Link hướng dẫn chi tiết: Hướng dẫn sử dụng Shortcode bài viết.

4. Bộ lọc Thư viện & Lịch sử đọc

Hệ thống lọc mới giúp người dùng dễ dàng sắp xếp truyện đã theo dõi hoặc đã đọc gần đây theo nhu cầu cá nhân.

Cách hoạt động

• Trang Thư viện: mặc định sắp xếp theo “Mới theo dõi”, có thể chuyển sang “Đọc gần đây”.
• Trang Lịch sử: mặc định sắp xếp theo “Đọc gần đây”, có thể chuyển sang “Cũ nhất trước”.

Dropdown lọc sử dụng giao diện UIkit đồng bộ với các thành phần điều hướng khác và tự động xử lý URL param để giữ nguyên lựa chọn khi tải lại trang.

5. Hệ thống Thử Thách Đọc Truyện (Reading Challenge)

Tính năng này tạo ra các mốc đọc truyện (100, 200, 500 chương…) kèm phần thưởng tự động để tăng động lực cho người đọc trung thành.

Cách cấu hình

• Trong theme settings, nhập cấu hình mốc theo định dạng: chapters:exp:coin:cash, phân cách bằng dấu ;.
• Ví dụ: 100:10:20:0;200:20:50:10;500:50:100:20

Cách hoạt động

• Người dùng khi đạt mốc sẽ nhận được phần thưởng tương ứng (EXP, Coin, Cash).
• Hệ thống tự động ghi log giao dịch với nguồn reading_challenge.
• Gửi thông báo hộp thư đến khi hoàn thành thử thách, có ghi rõ phần thưởng nhận được.
• Phát hiện và loại bỏ trùng lặp nhờ lưu trữ bằng user meta.

6. Tổng kết

Các tính năng mới trong phiên bản 1.3.0 và 1.2.8 giúp tăng tính cá nhân hoá, tăng tương tác giữa tác giả và độc giả, đồng thời tạo động lực cho người dùng duy trì thói quen đọc truyện. Hãy cập nhật ngay và tận dụng toàn bộ sức mạnh mà hệ thống mang lại!