Starlight Markdown Blocks - Hướng dẫn chi tiết

Starlight Markdown Blocks - Hướng dẫn chi tiết

Tổng quan

starlight-markdown-blocks là một plugin mở rộng cú pháp Markdown asides của Starlight, cho phép bạn tạo các custom block types.

Ví dụ: giống như bạn dùng :::tip trong Starlight, bạn có thể thêm hỗ trợ cho cú pháp như :::my-custom-block và kiểm soát cách nó render.

Cài đặt

Bước 1: Cài đặt package

npm i starlight-markdown-blocks

hoặc

pnpm add starlight-markdown-blocks

Bước 2: Thêm plugin vào cấu hình

astro.config.mjs

import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import starlightMarkdownBlocks from 'starlight-markdown-blocks';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightMarkdownBlocks({
          blocks: {
            // Blocks configuration
          },
        }),
      ],
    }),
  ],
});

Cấu hình Blocks

Bạn có thể cấu hình blocks bằng cách thêm các entries vào object blocks.

Mỗi key trong blocks sẽ trở thành tên bạn có thể sử dụng trong Markdown files. Ví dụ: nếu bạn thêm key idea, bạn có thể dùng :::idea trong Markdown files.

Ví dụ cấu hình

import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import starlightMarkdownBlocks, { Aside } from 'starlight-markdown-blocks';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightMarkdownBlocks({
          blocks: {
            // Custom Aside với label, color, icon tùy chỉnh
            idea: Aside({ label: 'Idea', color: 'green', icon: '💡' }),

            // Custom block với HTML render
            figure: {
              render: ({ h, label, children }) =>
                h('figure', {}, [...children, h('figcaption', {}, label)]),
            },
          },
        }),
      ],
    }),
  ],
});

Cách sử dụng trong Markdown

Với cấu hình trên, bạn có thể dùng:

:::idea
I just thought of something!
:::

:::figure[— Tác giả, Tên sách]
> Trích dẫn
:::

Các loại Blocks có sẵn

1. Aside Helper

import { Aside } from 'starlight-markdown-blocks';

blocks: {
  tip: Aside({ label: 'Tip', color: 'purple', icon: '💡' }),
  warning: Aside({ label: 'Warning', color: 'orange', icon: '⚠️' }),
  danger: Aside({ label: 'Danger', color: 'red', icon: '🚨' }),
}

2. Draft Block

Cho phép tạo block nháp:

import { draft } from 'starlight-markdown-blocks';

blocks: {
  draft: draft(),
}

Sử dụng:

:::draft[Đang viết dở]
Nội dung chưa hoàn thiện
:::

Tạo Custom Block

Bạn có thể tạo custom block với hàm render:

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

Sử dụng:

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

Tích hợp với dự án

Terminal Block cho claw-style

Để tạo Terminal block giống như claw.ai.vn:

import { Aside } from 'starlight-markdown-blocks';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightMarkdownBlocks({
          blocks: {
            terminal: {
              render: ({ h, label, children }) => {
                // Tạo HTML cho terminal
                return h('div', { class: 'terminal-block' }, [
                  h('div', { class: 'terminal-header' }, [
                    h('span', { class: 'terminal-buttons' }, [
                      h('span', { class: 'close' }),
                      h('span', { class: 'minimize' }),
                      h('span', { class: 'maximize' }),
                    ]),
                    h('span', { class: 'terminal-title' }, label || 'Terminal'),
                  ]),
                  h('pre', { class: 'terminal-body' }, children),
                ]);
              },
            },
          },
        }),
      ],
    }),
  ],
});

CSS cho Terminal:

.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%;
}

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

.terminal-title {
  color: #ccc;
  font-family: monospace;
  font-size: 12px;
}

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

Sử dụng trong bài viết

:::terminal[Install Node.js]
$ node --version
v20.11.0
$ npm --version
10.2.4
:::

:::tip[Mẹo]
Sử dụng npx để chạy packages mà không cài global
:::

Kết luận

starlight-markdown-blocks là giải pháp hoàn hảo để tạo các custom blocks trong Starlight mà không cần dùng đến Svelte components. Điều này giúp:

• Không cần import Svelte trong MDX
• Tránh các lỗi build
• Tạo giao diện đẹp như claw.ai.vn

Tham khảo

• Starlight Markdown Blocks Docs
• Starlight Official Docs