Hiển thị code và syntax highlighting

12

Trong tài liệu kỹ thuật, code không chỉ là nội dung minh hoạ mà còn là thông tin cốt lõi. Việc hiển thị code rõ ràng, dễ đọc và đúng ngữ cảnh giúp người đọc hiểu nhanh và tránh sai sót khi áp dụng.

Init Docs không xử lý syntax highlighting trực tiếp. Thay vào đó, theme được thiết kế để hoạt động tốt với plugin Prismatic, đảm nhiệm toàn bộ việc hiển thị và tô màu code.

Nguyên tắc hiển thị code trong Init Docs

Init Docs ưu tiên cách hiển thị code đơn giản, chuẩn HTML và dễ bảo trì.

  • Không dùng block phức tạp hoặc page builder
  • Không nhúng code inline trong đoạn văn dài
  • Tách code thành khối rõ ràng để dễ đọc và sao chép

Cách tiếp cận này phù hợp với tài liệu kỹ thuật dài hạn.

Vai trò của Prismatic

Prismatic chịu trách nhiệm xử lý syntax highlighting cho code block trong Init Docs.

Khi Prismatic được cài đặt và kích hoạt:

  • Code block được tô màu theo ngôn ngữ
  • Giữ format và indentation chính xác
  • Không ảnh hưởng tới hiệu năng trang

Init Docs chỉ đảm bảo markup HTML sạch để Prismatic hoạt động đúng.

Chèn code trong Editor

Trong trình soạn thảo, việc chèn code được thực hiện thông qua nút Chèn code. Editor sẽ tạo sẵn khối pre và code cho bạn.

Bạn chỉ cần:

  • Chọn ngôn ngữ phù hợp
  • Dán đoạn code cần hiển thị
  • Giữ nguyên cấu trúc khối code

Prismatic sẽ tự động xử lý phần còn lại.

Cấu trúc code block chuẩn

Init Docs khuyến nghị sử dụng cấu trúc HTML chuẩn cho code block như sau:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'init', function () {
    register_post_type( 'docs', [
        'label'  => 'Documentation',
        'public' => true,
    ] );
} );

Trong đó:

  • Thẻ pre dùng để giữ định dạng
  • Thẻ code chứa nội dung code
  • Class language-php xác định ngôn ngữ cho Prismatic

Ngôn ngữ code được hỗ trợ

Prismatic hỗ trợ nhiều ngôn ngữ lập trình phổ biến. Khi chèn code, bạn chỉ cần thay đổi class tương ứng, ví dụ:

  • language-php
  • language-javascript
  • language-css
  • language-markup
  • language-json

Việc chỉ định đúng ngôn ngữ giúp code được tô màu chính xác và dễ đọc hơn.

Khi nào nên dùng code block?

Bạn nên sử dụng code block khi:

  • Hướng dẫn cấu hình hoặc thiết lập
  • Minh hoạ ví dụ lập trình
  • Cung cấp đoạn mã để người đọc sao chép

Không nên dùng code block cho các đoạn văn bản thông thường hoặc mô tả ngắn.

Lưu ý khi viết tài liệu có code

Để code trong tài liệu dễ sử dụng, bạn nên:

  • Giữ code ngắn gọn và đúng trọng tâm
  • Không trộn nhiều ngôn ngữ trong một khối code
  • Đảm bảo code có thể đọc độc lập

Code rõ ràng giúp tài liệu dễ hiểu và giảm rủi ro áp dụng sai.

Tổng kết

Init Docs kết hợp với Prismatic mang lại cách hiển thị code đơn giản, rõ ràng và hiệu quả cho tài liệu kỹ thuật. Chỉ cần sử dụng khối pre và code đúng chuẩn, bạn có thể trình bày code một cách dễ đọc và nhất quán trong toàn bộ hệ thống tài liệu.

Bài viết liên quan