Elastic UI (EUI) 项目文档编写指南

Elastic UI (EUI) 项目文档编写指南

eui Elastic UI Framework 🙌 项目地址: https://gitcode.com/gh_mirrors/eu/eui

前言

在开发 Elastic UI (EUI) 组件库时，高质量的文档是确保开发者能够正确使用组件的关键。本文将详细介绍如何为 EUI 项目编写规范化的文档，包括文档结构、内容组织、特殊组件使用等最佳实践。

文档基础架构

文件与目录结构

EUI 文档采用 Markdown 格式编写，使用 .mdx 扩展名，这种格式允许在 Markdown 中嵌入 React 组件。文档存放在 docs 目录下，目录结构直接对应网站的导航结构。

文件命名规范：

• 使用 kebab-case 命名法（如 my-component.mdx）
• 避免使用 EUI 常规的 snake_case 命名方式

文档元数据（Front Matter）

每个文档文件顶部需要包含 YAML 格式的元数据，用于配置文档的基本信息：

---
id: unique-document-id
title: 文档标题
sidebar_label: 侧边栏显示名称
sidebar_position: 排序位置
description: 文档描述
---

文档内容组织

组件文档标准结构

每个组件文档应遵循以下标准结构：

1. 简介：组件的基本介绍和用途
2. 基础示例：展示组件的最基本用法
3. 使用场景（可选）：展示不同状态和使用案例
4. 最佳实践（可选）：包括 Do's 和 Don'ts
5. 属性表：组件的 Props 说明

内容分块（Partials）

对于内容较长的文档，可以将内容拆分为多个文件：

components/
  modal/
    _guidelines.mdx   # 最佳实践部分
    _usage.mdx        # 使用场景部分
    index.mdx         # 主文档

在主文档中通过导入方式引入：

import Usage from './_usage.mdx';

## 使用场景

<Usage />

文档编写技巧

标题层级

使用标准的 Markdown 标题语法：

# 一级标题
## 二级标题
### 三级标题

注意保持标题层级的逻辑性和一致性。

链接处理

推荐使用 Markdown 标准链接语法：

[链接文本](相对路径/文件.mdx)

对于跨文档链接，使用相对路径并包含文件扩展名。

提示框（Admonitions）

使用特殊语法创建带图标的提示框：

:::info 提示标题
提示内容
:::

支持的类型包括：note、tip、info、accessibility、warning、danger。

代码块

基础代码块语法：

```tsx
const MyComponent = () => <div>Hello</div>;
```

对于可交互的代码演示，添加 interactive 标记：

```tsx interactive
export default () => <EuiButton>Click me</EuiButton>
```

高级文档功能

动态演示（Demo 组件）

对于复杂演示场景，可以使用内置的 Demo 组件：

<Demo previewPadding="l">
```tsx
import { EuiButton } from '@elastic/eui';

export default () => <EuiButton>按钮</EuiButton>

```

Demo 组件支持以下属性：

• previewPadding：调整内边距
• isSourceOpen：默认是否显示源代码
• previewWrapper：自定义包装组件

全屏示例

对于需要全屏展示的复杂示例，建议创建 Storybook 故事并链接：

## 复杂表单示例

这个示例展示了如何构建复杂的表单布局。

```mdx-code-block
import { StorybookLink } from '@site/src/components';

```

属性表格

组件属性表应放在文档最后：

## 属性

```mdx-code-block
import docgen from '@elastic/eui-docgen/dist/components/button';

```

视觉元素处理

图片使用

基础 Markdown 语法：

![替代文本](./images/example.webp)

需要特殊样式时使用 img 标签：

import exampleImg from './images/example.webp';

<img
  src={exampleImg}
  alt="替代文本"
  style={{ maxWidth: '480px' }}
/>

Figma 嵌入

可以直接嵌入 Figma 设计文件：

<FigmaEmbed 
  url="https://www.figma.com/file/example" 
  title="设计稿标题" 
/>

最佳实践建议

1. 优先使用 Markdown：相比直接使用 React 组件，Markdown 更易于维护
2. 避免过度嵌套：侧边栏导航最多保持 2-3 级深度
3. 保持一致性：同类内容的组织和呈现方式保持一致
4. 注重可读性：复杂示例应拆分到单独文件
5. 完整属性说明：确保所有组件属性都有详细说明

通过遵循这些指南，您可以为 EUI 项目贡献高质量、易维护的文档，帮助开发者更好地理解和使用组件库。

eui Elastic UI Framework 🙌 项目地址: https://gitcode.com/gh_mirrors/eu/eui