Skip to main content

根目录 > docs

Docs 模块文档

模块职责​

docs 模块负责管理项目的文档内容，包括教程、API 文档、用户指南等。采用 Markdown 格式，支持 Front Matter 元数据配置和侧边栏自动生成。

入口与启动​

主要入口文件​

  • 文档首页: intro.md - 教程介绍页面
  • 侧边栏配置: ../sidebars.ts - 文档导航结构
  • 分类配置: 各子目录的 _category_.json 文件

文档目录结构​

docs/
├── intro.md                    # 文档首页
├── tutorial-basics/            # 基础教程
│   ├── _category_.json        # 分类配置
│   ├── create-a-document.md   # 创建文档教程
│   ├── create-a-page.md       # 创建页面教程
│   ├── create-a-blog-post.md  # 创建博客教程
│   ├── markdown-features.mdx  # Markdown 功能
│   ├── deploy-your-site.md    # 部署教程
│   └── congratulations.md     # 完成祝贺页面
└── tutorial-extras/            # 扩展教程
    ├── _category_.json        # 分类配置
    ├── manage-docs-versions.md # 版本管理
    ├── translate-your-site.md  # 站点翻译
    └── img/                   # 教程图片
        ├── docsVersionDropdown.png
        └── localeDropdown.png

对外接口​

Front Matter 配置接口​

---
title: 文档标题
sidebar_position: 1          # 侧边栏位置
slug: custom-url             # 自定义 URL
description: 文档描述        # SEO 描述
tags: [tag1, tag2]          # 标签
authors: [author1]          # 作者
custom_field: custom_value  # 自定义字段
---

分类配置接口​

{
  "label": "分类名称",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "分类描述"
  }
}

侧边栏配置接口​

const sidebars: SidebarsConfig = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}]
};

关键依赖与配置​

Docusaurus 文档插件​

  • @docusaurus/plugin-content-docs - 文档内容处理
  • 自动侧边栏生成
  • Markdown/MDX 解析
  • 版本管理支持

内容格式支持​

  • Markdown: 标准 Markdown 语法
  • MDX: 支持 React 组件的 Markdown
  • Front Matter: YAML 格式元数据
  • 代码块: 语法高亮和复制功能

主题集成​

  • Docusaurus 经典主题
  • 响应式布局
  • 深色/浅色主题切换
  • 搜索功能集成

数据模型​

文档元数据结构​

interface DocumentMetadata {
  title: string;
  description?: string;
  sidebar_position?: number;
  slug?: string;
  tags?: string[];
  authors?: string[];
  last_updated?: string;
}

分类数据结构​

interface CategoryMetadata {
  label: string;
  position?: number;
  link?: {
    type: 'generated-index' | 'doc';
    description?: string;
  };
}

侧边栏数据结构​

interface SidebarItem {
  type: 'doc' | 'category' | 'autogenerated';
  id?: string;
  label?: string;
  items?: SidebarItem[];
  customProps?: Record<string, any>;
}

测试与质量​

内容质量检查​

  • 链接验证: 内部和外部链接有效性
  • 图片完整性: 图片资源加载检查
  • Markdown 语法: 格式正确性验证
  • 元数据完整: Front Matter 必填字段检查

可访问性测试​

  • 图片 alt 属性
  • 标题层级结构
  • 代码语言标识
  • 键盘导航支持

SEO 优化检查​

  • 页面标题和描述
  • 元标签完整性
  • 结构化数据
  • URL 友好性

常见问题 (FAQ)​

Q: 如何调整文档在侧边栏中的顺序？​

A: 在 Front Matter 中设置 sidebar_position 数值，数值越小越靠前。

Q: 如何创建文档分类？​

A: 在子目录中创建 _category_.json 文件，配置分类信息。

Q: 如何在文档中嵌入 React 组件？​

A: 将文件扩展名改为 .mdx，可以直接导入和使用 React 组件。

Q: 如何自定义文档 URL？​

A: 在 Front Matter 中设置 slug 字段来自定义 URL 路径。

Q: 如何添加代码块的语法高亮？​

A: 在代码块开始标记后添加语言标识，如 ````javascript`。

相关文件清单​

核心文档​

  • intro.md - 文档首页和介绍
  • tutorial-basics/ - 基础教程集合
  • tutorial-extras/ - 高级功能教程

配置文件​

  • ../sidebars.ts - 侧边栏配置
  • tutorial-basics/_category_.json - 基础教程分类
  • tutorial-extras/_category_.json - 扩展教程分类

资源文件​

  • tutorial-extras/img/ - 教程相关图片
  • 各文档中引用的代码示例和资源

内容创作指南​

文档命名规范​

  • 使用小写字母和连字符：file-name.md
  • 避免使用空格和特殊字符
  • 保持文件名简洁且描述性强

Front Matter 最佳实践​

  • 必填字段：title
  • 有序文档：设置 sidebar_position
  • SEO 优化：填写 description
  • 分类管理：添加适当的 tags

Markdown 编写规范​

  • 使用标准的 Markdown 语法
  • 标题层级不要跳跃 (H1 -> H3)
  • 代码块指定语言类型
  • 图片提供 alt 文本

内容组织原则​

  • 按逻辑关系组织文档结构
  • 保持页面长度适中
  • 提供清晰的导航路径
  • 相关文档互相引用

变更记录 (Changelog)​

2025-10-25 18:00:53​

  • 创建 docs 模块文档
  • 分析现有文档结构和配置
  • 制定内容创作规范和最佳实践