Sử dụng shortcode [demo]

18

Trong Init Docs, shortcode [demo] được sử dụng để quyết định vị trí hiển thị demo trong nội dung bài viết. Shortcode này cho phép bạn chèn các ví dụ HTML, CSS và JavaScript trực tiếp vào tài liệu, đúng ngữ cảnh và đúng mạch đọc.

Demo chỉ được hiển thị khi bài viết có nội dung demo tương ứng trong Demo metabox.

Vai trò của shortcode [demo]

Shortcode [demo] đóng vai trò là điểm neo cho demo trong nội dung bài viết.

Thay vì hiển thị demo cố định ở đầu hoặc cuối bài, Init Docs cho phép bạn:

  • Đặt demo ngay sau phần giải thích lý thuyết
  • Chèn demo giữa các section
  • Kiểm soát luồng đọc và quan sát kết quả

Nếu không sử dụng shortcode, demo sẽ không được render.

Quy trình hiển thị demo

Quy trình hoạt động của demo trong Init Docs như sau:

  • Nhập HTML, CSS và JavaScript trong Demo metabox
  • Lưu bài viết
  • Chèn shortcode [demo] vào nội dung
  • Demo được hiển thị đúng tại vị trí shortcode

HTML được render tại vị trí shortcode, trong khi CSS và JavaScript được nạp riêng cho trang bài viết.

Ví dụ demo: Nút bấm với hiệu ứng ripple

Ví dụ dưới đây minh hoạ cách sử dụng shortcode [demo] để hiển thị một demo đơn giản: một nút bấm có hiệu ứng ripple khi click.

Demo này sử dụng HTML, CSS và JavaScript thuần, phù hợp cho tài liệu kỹ thuật.

Nội dung Demo metabox

Để tạo demo trên, bạn cần nhập nội dung tương ứng vào các trường trong Demo metabox.

HTML

<button class="demo-ripple-btn">
  Click me
</button>

CSS

.demo-ripple-btn {
  position: relative;
  overflow: hidden;
  padding: 12px 20px;
  border: none;
  background: #1e87f0;
  color: #fff;
  font-size: 14px;
  cursor: pointer;
  border-radius: 4px;
}

.demo-ripple-btn span {
  position: absolute;
  border-radius: 50%;
  transform: scale(0);
  animation: ripple 600ms linear;
  background-color: rgba(255, 255, 255, 0.6);
}

@keyframes ripple {
  to {
    transform: scale(4);
    opacity: 0;
  }
}

JavaScript

document.addEventListener('click', function (e) {
  const button = e.target.closest('.demo-ripple-btn');
  if (!button) return;

  const circle = document.createElement('span');
  const diameter = Math.max(button.clientWidth, button.clientHeight);
  const radius = diameter / 2;

  circle.style.width = circle.style.height = diameter + 'px';
  circle.style.left = e.clientX - button.getBoundingClientRect().left - radius + 'px';
  circle.style.top = e.clientY - button.getBoundingClientRect().top - radius + 'px';

  const ripple = button.querySelector('span');
  if (ripple) {
    ripple.remove();
  }

  button.appendChild(circle);
});

Lưu ý khi sử dụng shortcode [demo]

Khi sử dụng demo trong tài liệu, bạn nên lưu ý:

  • Chỉ đặt một demo cho mỗi vị trí cần minh hoạ
  • Giữ demo đơn giản và tập trung vào nội dung đang giải thích
  • Tránh demo quá phức tạp gây phân tâm

Demo nên đóng vai trò minh hoạ, không thay thế nội dung giải thích.

Khi nào nên dùng demo?

Shortcode [demo] phù hợp trong các trường hợp:

  • Minh hoạ kết quả CSS hoặc JavaScript
  • Hướng dẫn UI, interaction
  • Giải thích hành vi kỹ thuật khó hình dung

Với nội dung chỉ mang tính tham khảo, code block thông thường là đủ.

Tổng kết

Shortcode [demo] là cầu nối giữa nội dung tài liệu và ví dụ trực quan trong Init Docs. Khi được sử dụng đúng cách, demo giúp tài liệu dễ hiểu hơn, trực quan hơn và phù hợp với các hướng dẫn kỹ thuật dành cho developer.

Bài viết liên quan