开发文档指南

本指南将帮助你了解如何在 SciecneOL Docs 中创建、修改和维护文档。遵循这些指南可确保文档的一致性和高质量。

文档项目的 Github 仓库地址为：ScienceOL/docs，请自行完成仓库的克隆操作。

文档结构

ScienceOL 的文档使用 MDX（Markdown + JSX）格式，并采用以下目录结构组织：

/src/app/
├── (cn)/                   # 中文文档
│   ├── workflow/           # 工作流相关文档
│   ├── development/        # 开发相关文档
│   └── ...
└── en/                     # 英文文档（结构类似）

每个文档目录通常包含以下文件：

  • page.mdx - 目录主页
  • layout.tsx - 定义页面布局和导航
  • 子目录及其对应 page.mdx

创建新文档

创建新文档之前，你应当已经在本地启动文档开发环境。clone 本项目并在根目录执行 yarn install && yarn dev 即可启动 docs 开发环境。

如果你使用 VS Code 进行开发，推荐安装 MDX 及 React 扩展提升书写体验。

创建一个新的文档页面需遵循以下步骤：

  1. 在适当的目录结构下创建 .mdx 文件，如：
/src/app/(cn)/development/your-feature/page.mdx

项目中的 /src/app/(cn)/development/your-feature/page.mdx 路径对应网页上的 /development/your-feature url

  1. 添加必要的前置元数据：
export const metadata = {
  title: '你的文档标题',
  description: '简短的描述',
}

{/* 可选添加 */}
export const sections = [
  { title: '第一部分', id: 'di-yi-bu-fen' },
  { title: 'id 必须与 title 关联', id: 'id-bi-xu-yu-title-guan-lian' },
]

Sections 部分为可选添加，主要用于渲染为左侧目录树。大部分情况下无需声明。若需声名，id 必需与 title 关联。

  1. 在相应模块父目录的 navigation.ts 文件中添加导航链接。

相应模块父目录是指 /app 路径下的二级目录，例如对于 /app/(cn)/development/your-feature/page.mdx，相应的父目录为 /app/(cn)/development/

{
  title: '文档类别',
  links: [
    // ... 现有链接
    { title: '你的文档', href: '/development/your-feature' },
  ],
}

重要提示：href 的路径应与你的文档文件夹路径相同，例如对于 /development/your-feature，则对应 /src/app/(cn)/development/your-feature/page.mdx 文件。

编写指南

为保持文档一致性和质量，请遵循以下编写指南：

  1. 标题层次：使用单个 # 作为页面主标题，## 作为主要章节，### 作为子章节，以此类推。

目前章节内导航到二级目录 ## .

  1. 命名约定：

    • 文件名统一使用 page.mdx
    • 目录名使用小写字母和连字符，如 api-reference

  2. 内容格式：

    • 使用简洁明了的语言
    • 代码块应该指定语言，如 ```tsx
    • 添加适当的注释和说明
    • 对于重要信息，使用组件如 <Note> 或 <Warn> 突出显示

  3. 国际化：

    • 中文内容放在 (cn) 目录下
    • 英文内容放在 en 目录下，与 (cn) 目录对应

组件使用

项目提供了多种可在 MDX 中使用的组件，以增强文档效果：

常见组件

以下是一些你可以在文档中使用的核心组件：

  • <Note> - 提示信息
  • <Warn> - 警告信息
  • <CodeGroup> - 代码分组展示
  • <Properties> - 属性列表
  • <Propertie> - 单个属性
  • <Row> 和 <Col> - 布局组件
  • <Button> - 按钮组件

你也可以为标题添加 API 信息，例如：

## Example {{ tag: 'POST', label: '/v1/example' }}

这是一个提示信息。

这是一个警告信息。

示例代码组

GET
/v1/example
function Example() {
    return <div>Example</div>
}
  • Name
    properties
    Type
    string
    Description

    properties 用于包裹在 propertie 组的外层

  • Name
    propertie
    Type
    string
    Description

    propertie 描述单个属性

代码块使用

代码块应当指定语言，并可以添加标题和其他属性：

    ```tsx {{ title: '示例代码' }}
    function Example() {
        return <div>Example</div>
    }

对应的展示效果如下：

示例代码

function Example() {
    return <div>Example</div>
}

贡献流程

准备工作

  1. 从 main 分支创建新分支，使用以下命名格式：

    • 新功能文档：feat/docs-feature-name
    • 文档错误修复：fix/docs-issue-description

  2. 在本地修改文档并测试

提交变更

  1. 提交代码时使用清晰的提交信息，如：

    • docs: add workflow tutorial
    • fix: correct api endpoint information

  2. 推送分支到远程仓库

创建 Pull Request

  1. 创建 Pull Request 到 main 分支

  2. 在 PR 描述中包含：

    • 变更摘要
    • 相关的 issue 链接（如有）
    • 任何需要审阅者特别注意的地方

当你创建 PR 后，Netlify 会自动构建预览版本。你可以通过预览链接检查文档的实际效果。

审阅和合并

  1. 等待至少一个审阅者批准你的 PR
  2. 解决审阅过程中提出的任何问题
  3. PR 批准后，它将被合并到 main 分支

部署

文档合并到 main 分支后，将自动部署到 https://cloudocs.netlify.app/

Was this page helpful?