Starlight TypeDoc - Tự động Generate Documentation từ TypeScript

Tổng quan

Starlight TypeDoc (starlight-typedoc) là một plugin cho phép tự động generate tài liệu documentation từ TypeScript code sử dụng TypeDoc.

So sánh

Approach	Ưu điểm	Nhược điểm
Viết MDX thủ công	Linh hoạt, control hoàn toàn	Tốn thời gian
starlight-typedoc	Tự động, sync với code	Ít linh hoạt về layout

Khi nào nên dùng?

✅ Nên dùng khi:

• Dự án có nhiều TypeScript interfaces, types cần document
• Library/framework cần API docs tự động
• Muốn docs luôn sync với code

❌ Không cần khi:

• Tài liệu hướng dẫn (vẫn nên viết thủ công)
• Docs cần nhiều custom styling
• Code ít, chủ yếu là nội dung giải thích

Cài đặt

npm install @zenoo/typedoc-plugin-starlight

Cấu hình trong astro.config.mjs:

import starlight from '@astrojs/starlight';
import starlightTypeDoc from 'starlight-typedoc';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightTypeDoc({
          entryPoints: ['../src/**/*.ts'],
        }),
      ],
    }),
  ],
});

Cách hoạt động

1. Viết TypeScript code với JSDoc comments
2. Chạy npm run build
3. Plugin tự động generate trang docs từ code

/**
 * Calculate the sum of two numbers
 * @param a - First number
 * @param b - Second number
 * @returns Sum of a and b
 */
function add(a: number, b: number): number {
  return a + b;
}

Sẽ tự động tạo thành trang documentation với description, parameters, return type.

Kết luận

• starlight-typedoc: Phù hợp cho API documentation tự động
• MDX thủ công: Phù hợp cho tutorials và hướng dẫn
• Có thể kết hợp cả hai: dùng typedoc cho API, MDX cho guides

Tham khảo

• Starlight TypeDoc