跳转至

文档入门

ClientDocumentation 下的内容都以 Markdown 的形式记录，把你的文档以 Markdown 的形式编写好后提交至 Github，网站就会自动更新。

至此你需要做以下几个准备

  1. 了解 Markdown 的基础语法
  2. Git 的基础用法
  3. 加入我们的组织 YimiClient 以获得 ClientDocumentation 文档项目的权限

下载项目

首先你需要下载项目，下载项目需要 YimiClient 的权限，请联系 newbility523 获取。

通过以下指令下载项目到本地

git clone https://github.com/YimiClient/ClientDocumentation.git

编辑器环境搭建

编写文档需要意见趁手的工具，有两个 Markdown 编辑器推荐

  • Typora（买断付费，可试用）

  • VSCode（免费，需要插件支持）

图片上传

在使用编辑器插入图片到文档时，本地预览时正常的，但是发送给其他人浏览就会出现图片丢失的问题。这是因为文档引用的图片是一个本地地址。

所以为了处理这种文档需要分享的场景，用到的图片就必须上传到云端，也就是图床。而 Typora 会将图片上传至图床后，网络上的路径替换原有的路径，文档就可以方便的分享而不丢失图片了。

以下以 Typora + PicGo 的组合做配置介绍，如果使用 VSCode 获取其他编辑器，需要自行搜索图床设置。

安装、配置 PicGo

下载 PicGo 后，选中 图床设置/腾讯云COS 按照下图和表格内容一一对应

设置

image-20230802120707065

选项内容

选项 内容
COS version v5
SecretId AKIDqX6QUWGkxteGhuqY9Y4TjkiW3KL6btyp
SecretKey ICloud-Notes
Bucket newbility523-1252413540
AppId 1252413540
Area ap-guangzhou
Path PicBed

Warning

SecretKey 的内容是密码，需要找newbility523获取

Typora 端设置

打开设置，再 图像/上传服务器设定 中选择 PicGo.app。

image-20230802122815720

Danger

如果 Typora 设置的 通用 中没勾选中国区服务器，是无法在上传设定中选择 PicGo.app 的

上传文档

以本说明文档的上传为例（文件为get-started.md），当完成说明文档后想需要到下图效果，位于 文档说明/开始 中

image-20230802124639542

就需要在项目的 ./mkdocs.yml 文件的 nav 字段按照结构声明引用的文本，如：

nav:
  - 文档说明: 
    - 开始: contribute/get-started.md             # 插入到这里
    - 文档Demo: contribute/mkdoc-material-usage-demo.md

根据归档的规范，文档说明文件都放在项目的 ./docs/contribute 目录下。最后就是通过 Git 提交以上修改即可，网站检测到你的提交后会自动更新。

文档框架使用的是 Mkdocs+Mkdocs-material主题，所以会有一些拓展的写法样式，主题会根据这些写法调整展示内容形式，可以提升一定的阅读性。这方面会在下一章节给出说明。

Tip

即使一份完全没有特殊样式或者 Markdown 语法样式文档也是可以上传的。重要的是内容，而不是形式。