https://github.com/leancloud/docs

LeanCloud Documentation
https://github.com/leancloud/docs

documentation leancloud leanengine

Last synced: 2 days ago
JSON representation

LeanCloud Documentation

• Host: GitHub
• URL: https://github.com/leancloud/docs
• Owner: leancloud
• Created: 2024-08-28T06:19:38.000Z (3 months ago)
• Default Branch: master
• Last Pushed: 2024-09-09T03:53:39.000Z (2 months ago)
• Last Synced: 2024-10-30T00:52:28.368Z (15 days ago)
• Language: MDX
• Size: 116 MB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# TapTap 开发者中心文档

## 本地预览

```sh

yarn

yarn start

# 预览英文文档

yarn start --locale en

### 国际版预览中文文档：

yarn start --locale zh-hans

```

注意：`yarn start` 并不会检查坏链。如需检查坏链，需要运行 `yarn build`。坏链检查只会检查文档内部链接指向的页面是否存在，不会检查指向第三方网站的外部链接，也不会检查页内链接（hash link）。

## 贡献

我们欢迎所有 LeanCloud 用户以及公司同事修改文档或提交 issue 为我们贡献或者修正错误，LeanCloud 衷心感谢您的贡献。

**贡献方法及注意事项：**

* 搭建本地开发环境，需要 [Node.js](https://nodejs.org/en/download/package-manager) 18.0 或更高版本 （可以通过运行 `node -v` 命令来查看本地 Node.js 版本）。你可以使用 [nvm](https://github.com/nvm-sh/nvm) 管理同一台计算机上安装的多个 Node 版本。

* Fork 这个项目。

* 切换到本地 master 分支，git fetch 拉取远端最新修改到本地，如果远端 master 分支有修改，则将本地 master 分支 rebase 到最新的 master 分支上。

* 在 master 上新建分支，在新分支修改文档。

* 修改文档。

  * 参考下文介绍的目录结构，在 docs（中文文档）目录下修改文档内容。

  * 注意要同时在 i18n/en/docusaurus-plugin-content-docs/current（英文文档）目录下同步修改英文文档。

  * 插入配图、图表和 PPT 等，可参考下文详细介绍。

* 预览文档。运行 `yarn` 命令安装所需要依赖，运行 `yarn start` 命令可以本地预览。

* 预览没问题后，提交修改并发起 Pull Request，并指定 Reviewer。

  * Reviewer 同意修改后，才可以合并 Pull Request。

  * Pull Request 合并后，会自动发布上线。

  * Pull Request 合并后，可删除当前分支。

* 文档规范可参考 [中文文案风格指南](https://blog.taptap.dev/pages/chinese-copywriting-guide)。

## 目录结构

```

.

├── docs                                     中文文档

│   ├── ddos.mdx                             隐藏文档

│   └── sdk                                  顶栏菜单项

│       └── start                            侧栏菜单项

│           └── overview.mdx                 文档内容

├── i18n

│   └── en                                   英文文档

│       ├── code.json                        UI 翻译（用于文档内容以外的地方，如文档搜索）

│       ├── docusaurus-plugin-content-docs

│       │   ├── current                      全部文档内容，需与 `docs`（中文文档）结构一致

│       │   └── current.json                 侧栏菜单项翻译

│       └── docusaurus-theme-classic

│           └── navbar.json                  顶栏菜单项翻译

├── static                                   静态文件

│   └── img                                  文档配图

├── sidebars.js                              菜单配置

└── src

    ├── docComponents                        自定义组件（用于文档内容，如多编程语言）

    ├── pages                                文档以外的页面（目前只包含首页）

    ├── styles                               一些共享样式

    └── theme                                自定义组件（用于文档内容以外的地方，如文档搜索）

```

其中编辑人员常用的目录有：

- `docs`（中文文档）

- `i18n/en/docusaurus-plugin-content-docs/current`（英文文档）

- `static/img`（文档配图）

## 文档编写

### 名称风格

文件路径和文件名请注意和 URL 路径保持一致，比如 URL 路径为 `/docs/community/features/` 的页面，文件路径请使用 `/docs/community/features.mdx`。

### 文档前言（元信息 metadata）

位于文档头部可提供一些文档本身的信息，以 `---` 开头并以 `---` 结束。

> - `*` 为必填项，`[]` 为字段说明

> - 回退到 XXX：指如果没有设置该值则使用 XXX 作为替代

> - [完整文档](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter)

```markdown

---

title: *[正文的标题，同时也会显示在浏览器标签处]

sidebar_label: [显示在左侧边栏的标题，回退到 title]

sidebar_position: [数字，决定左侧边栏的顺序，数字越小越靠前]

slug: [URL 路径，一般情况下无需指定，回退到文件路径]

---

> 之后是你的文档内容

```

### 侧边栏

仅「一级导航」有侧边栏，分别为「游戏商店」、「游戏服务」、「设计资源」，分别对应 `docs` 目录下的 `store`、`sdk`、`design` 文件夹。

如需添加「一级导航」，请提需求到*技术支持*。如需添加次级导航，则需要调整目录结构，项目将自动以目录结构生成对应侧边栏（二级导航/.../N 级导航）。

如果不想文档出现在侧边栏，则可以放在「一级导航」同级，其他文档可以通过[链接到其他文档](#链接到其他文档)进行跳转，但此时目标页将不会显示侧边栏。这些文档需要在 YAML header 指定 `slug`，以免未来移动位置后 URL 改变；还需要指定 `noindex`，这样文档不会被文档搜索系统收录。

例子：

```markdown

---

title: 客服系统

slug: /sdk/tap-support/guide/

---

  

```

### 组件

可以在 `src/docComponents/doc.tsx` 中编写 React 组件并在 Markdown 文件（下称 md 文件）中引入。目前项目中已预设了部分组件可直接使用。

如需要其他预设，请提需求到*技术支持*。

```md

import { Gray, Blue, Red, Black, FaqLink } from '/src/docComponents/doc';

这些字将是红色

这些字将是灰色

[1. 开发者注册流程](/store/store-register/)

```

#### 多编程语言

多种编程语言的代码示例可以使用 `MultiLang` 组件：

````md

```cs

public static void GetAccessToken (Action action);

```

```java

public static AccessToken getCurrentToken;

```

```objectivec

+ (AccessToken *)getCurrentToken;

```

````

注意：

- 如果文件开头没有引入 `MultiLang` 组件，那么需要引入一下：`import { MultiLang } from '/src/docComponents/doc';`

- `` 后、`` 前，以及不同语言的代码片段之间都要空一行，否则 MDX 语法无法正确解析。

- 语言的顺序为 C#、Java、Objective-C，不能乱。

- 有些地方多语言代码示例使用 `Tabs` 组件，它的效果和 `MultiLang` 是等效的（实际上 `MultiLang` 最终会生成 `Tabs` 组件）。因为 `MultiLang` 更简洁，所以新编写的多语言代码示例推荐使用 `MultiLang`。

实际上，`MultiLang` 里不仅可以放入代码片段，还可以放入其他各种组件，只需保证：1) 内容顺序为 C#、Java、Objective-C，2) 不同编程语言内容在组件层级上是同级的。下面是一个例子：

````md

<>

```cs

public static void Login (LoginType loginType, string[] permissions);

```

**LoginType 参数说明**

| 参数             | 描述        |

| ---------------- | ----------- |

| LoginType.TAPTAP | TapTap 登录 |

>

<>

```java

/**

* @param type TapTap = 0

*/

public static void login(Activity activity, @LoginType.ThirdPartyType int type, String... permissions);

```

**LoginType 参数说明**

| 参数 | 描述        |

| ---- | ----------- |

| 0    | TapTap 登录 |

>

<>

```objectivec

+ (void)login:(TapBootstrapLoginType)type permissions:(NSArray *_Nullable)permissions;

```

**LoginType 参数说明**

| 参数                        | 描述        |

| --------------------------- | ----------- |

| TapBootstrapLoginTypeTapTap | TapTap 登录 |

>

````

上面的例子中，我们使用了空标签 `<>...>`（React 的 `Fragment` 组件）将 C#、Java、Objective-C 的不同内容包成三组。

同样，空标签和 markdown 之间也需要留出空行。

另外，由于 Docusaurus 的 TOC 生成并不能正确处理这种情况下的小标题（仅会根据第一个标签的内容生成小标题，切换标签后 TOC 的内容不变），请不要在 `MultiLang` 标签中使用 `h1`、`h2`、`h3` 级别的标题。

最后，某些文档面向的平台并不是 Unity、iOS、Android，这种情况下可以用 `kind` 参数指定使用 `MultiLang` 的变体，比如云引擎文档使用 ``，顺序为 JavaScript、Python、PHP、Java、C#、Go。

#### 图表

支持 [Mermaid](https://mermaid-js.github.io/mermaid/#/)。

在文件开头引入 `Mermaid` 组件：

```js

import Mermaid from "/src/docComponents/Mermaid";

```

然后在 `Mermaid` 组件的 `diagram` 属性中写 Mermaid 语法：

```js

|beforeDelete|H{error?}

H-->Y(Yes)

Y-->Z((interrupted))

H-->N(No)

N-->B[delete object on the cloud]

B -->|afterDelete|C((done))

`}

/>

```

#### PowerPoint 幻灯片

在文件开头引入 `OfficeDoc` 组件：

```js

import { OfficeDoc } from "/src/docComponents/doc";

```

然后在正文中插入组件：

```js

```

### 文档中的链接、配图、文件

#### 链接

##### 链接到其他文档

链接时使用基于对应语言文档根目录的绝对路径，**不要使用相对路径**。

- `docs/sdk/taptap-login/features.mdx` 在其他 md 文件中跳转需写作 `[跳转标题](/sdk/taptap-login/features/)`

- `docs/design/design-moment.mdx` 在其他 md 文件中跳转需写作 `[跳转标题](/design/design-moment/)`

- `i18n/en/docusaurus-plugin-content-docs/current/sdk/taptap-login/features.mdx` 在其他 md 文件中跳转需写作 `[跳转标题](/sdk/taptap-login/features/)`

- 标题跳转需要去除标点、将空格换成 `-` 并将大写字母改为小写，比如 `[1. 如何进行游戏认领？](/store/store-creategame#我的游戏已经被 TapTap 收录，可以进行游戏认领吗？)` 应写作 `[1. 如何进行游戏认领？](/store/store-creategame#我的游戏已经被-taptap-收录可以进行游戏认领吗)`

##### 链接到外部网站

- 要链接到 `https://docusaurus.io/`，在 md 文件中引用需写作 `[链接文本](https://docusaurus.io/)`

#### 配图

配图风格和规则参照 [Figma: DC 文档规范](https://www.figma.com/file/tbgT7SaWYfYkr6RPko9dZo/%E6%96%87%E6%A1%A3%E9%85%8D%E5%9B%BE-%E8%AE%BE%E8%AE%A1%E6%8C%87%E5%8D%97?node-id=0%3A1)，规范包括游戏界面处理、标注规则、流程图规则、敏感信息遮盖、多图排版。

##### 在文档中插入图片

- 要插入位于 `img/design-1.1.png` 的图片，在 md 文件中引用需写作 `![图片说明](/img/design-1.1.png)`

- 要插入位于 `https://img.tapimg.com/market/images/c53d78b9b120276b53f82aebb0d01537.png` 的图片，在 md 文件中引用需写作 `![图片说明](https://img.tapimg.com/market/images/c53d78b9b120276b53f82aebb0d01537.png)`

##### 如何用 Figma 为截图添加标注

1. 在 Figma 中新建一个文件，将截图拖放或粘贴（command V）到页面中的任意位置。

2. 打开[文档配图指南](https://www.figma.com/file/tbgT7SaWYfYkr6RPko9dZo/%E6%96%87%E6%A1%A3%E9%85%8D%E5%9B%BE-%E8%AE%BE%E8%AE%A1%E6%8C%87%E5%8D%97%E3%80%90%E8%AE%BE%E8%AE%A1%E3%80%91?node-id=113%3A91)，从中拷贝（command C）你想使用的标注组件。

3. 回到前面新建的文件，粘贴（command V）刚刚拷贝的标注组件。

4. 将标注组件拖拽到合适的位置并调整大小。

5. 如果调整好大小之后发现标注组件的边框太细或者里面的文本/箭头太小，可以适当缩小原始截图的大小（注意缩放截图时要按住 shift 以保持原始长宽比），然后重复第 4 步。

6. 如果截图需要多个标注，请重复第 2 至 5 步。注意更新标注组件里面用作序号的文本。

7. 选中所有元素（command A），然后按下 option command G（或者右击选中的内容，点击「Frame selection」）。此时包括截图和标注在内的所有元素会被包裹进一个 Frame（可以理解为其他平面设计软件中「画板」和「编组」的结合体）。

8. 点击右侧面板最下方的「Export」，保持默认设置，点击「Export _Frame 名称_」（如果没有改过 Frame 名称，那么这里默认会显示为「Export Frame 1」）。

##### Tips

- 可以用 Chrome 插件 GoFullPage 截图，之后再使用 Figma 完成敏感信息遮盖、标注等，最后导出图片。

- 一些需要绘制的图片：比如内嵌动态的很多图片，可以使用 UI/UX 同事的设计稿。

- IDE 或编辑器界面的截图：底色参考配图规范，尽量展示完整的界面。

#### 文件

视频等大文件可以上传到 LC 华北节点的 capacity-center 应用（App ID：lhzo7z96ayhad9flpynyiu79t2jpzuasz2ke8cdb09zduvug）。

0. 初次上传前，先找 jiangruoxu、suixiaoxu 加你为应用的协作者，之后即可通过 LC 控制台上传文件。

1. 登录 LC 控制台 > 数据存储 > 文件：

2. 点击「上传」按钮上传文件。上传完成后，文件表格中的 URL 即为文件的 URL。

图片等小文件请直接提交至仓库。

## 翻译相关

### md 文档文件翻译

请放在其他语言（如 `en`）文件夹「相同路径」下。如想翻译 `docs/tap-download.mdx` 文件，则需要把翻译文件放在 `i18n/en/docusaurus-plugin-content-docs/current/tap-download.mdx`。

### 文件夹翻译（如有困难可直接联系技术支持）

首先请确保通过 `_category_.json` 为文件夹设置了中文 label：

```json

{

  "label": "中文侧边栏名",

  "collapsed": true,

  "position": 3

}

```

在非中文 `docs` 目录下有一个 `current.json` 文件用来存放所有中文 label 对应的英文翻译。下面的示例展示了包含 `docs/sdk/taptap-login`（TapTap 登录）和 `docs/sdk/taptap-login/guide`（开发指南）这两个目录的翻译的 `current.json` 文件：

```json

{

  "sidebar.sdk.category.TapTap 登录": {

    "message": "TapTap Login",

    "description": "The label for category TapTap 登录 in sidebar sdk"

  },

  "sidebar.sdk.category.开发指南": {

    "message": "Guides",

    "description": "The label for category 开发指南 in sidebar sdk"

  }

}

```

## 文档发布注意事项

- 不支持 html 文件脚本，直接复制 markdown 过来的文件可能无法初始化

- 仔细检查 sidebars.js 结构，可能无法初始化左侧导航栏

- docusaurus.config.js/#themeConfig.items 可以配置多个 headerLinks，但是要与 sidebars.js 对应，否则无法初始化菜单栏

- 即便是代码块包裹的 dom 节点，也会无法编译，导致整个 md 无法加载。可以尝试用 markdown 转义符'\'试试

- 用不到的内容尽量删除（git 会保留历史）而不是注释掉，因为翻译人员不一定熟悉 HTML 注释标记，可能因此做无用功。

- 一定要本地运行一下，检查更改过的代码文件是否能正常打开再 pr

- 若端口冲突，可手动修改 package.json#start 脚本；可以添加外部访问 ip 段，或者指定全部 docusaurus start --port 3000 --host 0.0.0.0

## 优化图片

运行 `yarn optimg` 任务可以优化 `img` 下的 JPEG（有损压缩）和 PNG 图片（无损压缩）。这一任务运行时间较长，所以未加入构建环节，需要手动运行。建议过一段时间（比如一两个月）跑一下。

## 多版本

按照以下流程增加一个版本（`N` 表示当前版本；请将 `N` 替换为具体的数值）：

1. 确认当前仓库没有包含任何新版本（`N+1` 版本）的内容

2. 新建一个分支，比如 `vN`，运行 `yarn docusaurus docs:version vN`

3. 替换 `versioned_docs/version-vN/` 下的内链，替换的正则是 `\]\(/(sdk|store|design)` 替换值为 `](/vN/$1`

## 其他文档

[Docusaurus 文档介绍](https://docusaurus.io/zh-CN/docs/docs-introduction)