前端工程化实践：如何搭建可持续维护的技术文档架构

my-frontend-project/
├── docs/                      # 全局与架构文档（通常配合 VitePress / Docusaurus）
│   ├── .vitepress/
│   ├── guide/
│   │   ├── getting-started.md # 上手指南
│   │   └── architecture.md    # 架构设计
│   └── adr/                   # 架构决策记录
│       └── 001-use-zustand.md
├── packages/
│   └── ui-components/         # 组件库
│       └── src/
│           └── Button/
│               ├── Button.tsx
│               ├── Button.test.tsx
│               ├── Button.stories.tsx # 交互式文档 (Storybook)
│               └── README.md          # 针对该组件的补充说明
└── package.json

import React from 'react';

export interface ButtonProps {
  /** 
   * 按钮展示变体类型 
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'danger';

  /** 
   * 按钮内部文本或子元素 
   */
  children: React.ReactNode;

  /** 
   * 是否处于加载状态 
   * @default false
   */
  loading?: boolean;

  /** 
   * 点击事件回调 
   */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  children,
  loading = false,
  onClick,
}) => {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick} disabled={loading}>
      {loading ? 'Loading...' : children}
    </button>
  );
};

name: Build and Check Docs

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'packages/**/*.md'
      - 'packages/**/*.stories.tsx'

jobs:
  docs-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install Dependencies
        run: pnpm install

      - name: Check Broken Links & Lint Docs
        run: pnpm run docs:lint

      - name: Build Docs Site
        run: pnpm run docs:build