Tạo Custom Blocks với starlight-markdown-blocks

Giới thiệu

starlight-markdown-blocks là plugin chính thức cho phép tạo custom blocks trong Starlight mà không cần Svelte components. Đây là giải pháp thay thế hoàn hảo khi bạn gặp lỗi với Svelte trong MDX.

Cài đặt

npm install starlight-markdown-blocks

Cấu hình cơ bản

astro.config.mjs

import starlightMarkdownBlocks from 'starlight-markdown-blocks';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightMarkdownBlocks({
          blocks: {
            // Định nghĩa custom blocks ở đây
          },
        }),
      ],
    }),
  ],
});

Ví dụ: Terminal Block

Cấu hình

terminal: {
  render: ({ h, label, children }) =>
    h('div', { class: 'terminal-block' }, [
      h('div', { class: 'terminal-header' }, [
        h('div', { class: 'terminal-buttons' }, [
          h('span', { class: 'close' }),
          h('span', { class: 'minimize' }),
          h('span', { class: 'maximize' }),
        ]),
        h('span', { class: 'terminal-title' }, label || 'Terminal'),
      ]),
      h('div', { class: 'terminal-body' }, children),
    ]),
},

Cách sử dụng trong MDX

:::terminal[Install]
npm install package-name
:::

:::terminal[Run Server]
npm run dev
:::

Ví dụ: Callout Block

callout: {
  render: ({ h, label, children }) =>
    h('div', { class: 'callout-block' }, [
      h('div', { class: 'callout-header' }, label),
      h('div', { class: 'callout-content' }, children),
    ]),
},

Cách sử dụng

:::callout[Lưu ý]
Đây là thông tin quan trọng!
:::

CSS Styling

/* Terminal Block */
.terminal-block {
  background: #1e1e1e;
  border-radius: 8px;
  overflow: hidden;
  margin: 1rem 0;
}

.terminal-header {
  background: #2d2d2d;
  padding: 8px 12px;
  display: flex;
  align-items: center;
  gap: 8px;
}

.terminal-buttons {
  display: flex;
  gap: 6px;
}

.terminal-buttons span {
  width: 12px;
  height: 12px;
  border-radius: 50%;
}

.terminal-buttons .close { background: #ff5f56; }
.terminal-buttons .minimize { background: #ffbd2e; }
.terminal-buttons .maximize { background: #27c93f; }

.terminal-body {
  background: #1e1e1e;
  color: #ccc;
  padding: 16px;
  font-family: 'Fira Code', monospace;
}

So sánh với Svelte Components

Tiêu chí	starlight-markdown-blocks	Svelte Components
Setup	Plugin nhẹ	Cần integration
Props	Giới hạn (label, children)	Đầy đủ
Logic	Không hỗ trợ	Hỗ trợ đầy đủ
Performance	Nhanh	Chậm hơn
MDX tương thích	✅ Hoàn hảo	⚠️ Cần fix

Khi nào nên dùng?

• ✅ Terminal/code blocks
• ✅ Callouts với label
• ✅ Tabs đơn giản
• ❌ Components có logic phức tạp
• ❌ Interactive components

Kết luận

starlight-markdown-blocks là giải pháp tối ưu cho việc tạo custom blocks trong Starlight. Kết hợp với CSS để tạo giao diện đẹp mắt như Terminal block trong bài viết này.