欢迎投稿
投稿方式
方式一: 通过向文档工程 GitHub
仓库提交文档 PR
,具体方法查看下面《PR(Pull Request)投稿流程》章节;
方式二: 将 MarkDown
文档打包,通过企业微信或者邮箱发送到 huangmingqiang@uniontech.com
;
PR(Pull Request)投稿流程
1. Fork 文档仓库
访问地址:https://github.com/mikigo/docs 进入到文档工程仓库;
然后用你自己的 GitHub
账号登录;
点击右上角的 Fork
按钮:
点击 Fork 按钮
然后不用想,直接戳这里:
点击 Create Fork 按钮
稍等片刻,就把此仓库 Fork
到你的 GitHub
中了;
2. 克隆这个 Fork 的项目
将你自己的 GitHub
中 Fork
的这个项目克隆下来:
Git Clone
终端输入:
git clone git@github.com:king123666/docs.git
其中 git@github.com:king123666/docs.git
可以直接用从网站上复制的;
不出意外的话就把仓库拉到本地了;
3. 提交PR
编辑文档
上一步之后本地就有文档工程,之后你就可以在里面新增或修改文档,这部分由于涉及到一些技巧和规范,我在后面单独开了一章来讲解;
提交你的新增或修改的内容到 Fork 仓库:
3.1 同步 Fork 仓库
在你 Fork
的仓库右上角点这里:
同步代码
确保 Fork 的仓库和原仓库保持同步;
3.2 提交 GitHub
添加git提交模板
在 ~
目录下新建文件,并命名为 gitcommit_template
将以下内容写入文件当中:
# commit type :fix(问题修复)、feat(功能开发)、style(风格修改)、refactor(重构)、docs(文档)、chore(其他)、test(测试) + 简单描述. 默认fix,根据情况修改
fix:
# 详细说明代码的改动,包含代码的实现思路,以及为什么这么做,可能会影响哪些功能。对于代码的审核者,需要从这段描述中能完全理解代码中所有改动的内容
Description:
# 写一段面向于产品的总结性内容,用于自动生成crp上的changlog,需要注意的事,这段描述必须从产品的角度考虑。
Log:
# 关联pms上的bug号,提交后,则会自动在pms对应bug信息页面添加备注,关联本次提交。若本次提交为修复bug相关,则请取消注释
#Bug:
# 修复 github issue
#Issue:
# 关联pms上的任务号,提交后,则会自动在pms对应任务信息页面添加备注,关联本次提交。若本次提交为任务相关,则请取消注释
#Task:
命令行执行:
git config --global commit.template ~/gitcommit_template
此命令将模板加入到 git
的提交模板中。
添加 commit
信息
git add 后面加文件名称
git add . # 表示添加所有文件
使用这条命令注意有些临时文件不要提交到仓库了。
git commit -a
之后在 fix:
后面(注意冒号后面必须加空格)写本地提交的 commit
信息,然后就可以提交代码了
git push
这样就把你新增或修改的内容提交到你 Fork 的仓库中了;
3.3 提交 PR
回到 GitHub
网站点这里:
开启PR
再点这里:
创建PR
然后你可以写一些你的描述,再点这里:
确认创建PR
好了,这样就完成了一个 PR
,你可以在这里查看:
查看PR
编辑文档
这个章节默认你已经把文档工程拉到本地了,如果还没有请参考前面 《PR(Pull Request)流程》1、2 章节;
1. 部署工程环境
在项目根目录下,终端输入:
bash env.sh
2. 目录结构
docs
├── docs <-- 这个docs目录
├── env.sh
├── LICENSE
├── node_modules
├── package.json
├── pnpm-lock.yaml
└── README.md
咱们啥也别管,直接掏 docs
目录:
docs
├── 编程语言
├── 常见问题
├── 读书笔记
├── 规范文档
├── 技术文档
├── 前后端
├── 人工智能
├── 投稿.md
├── 网络爬虫
├── 自动化技术
├── comments.md
├── index.md
├── Linux
├── public <-- 图片资源存放目录
└── release.md
上面是按文档类型做的划分,如果是新增文档,你看看你写的内容方向是属于哪个,那就在哪个目录下写文档,文档只支持 MarkDown
格式;
比如你要写的内容是 Linux 方向的:
Linux
├── 方案教程
│ ├── 配置开机自启服务.md
│ └── ...
├── 工具使用
│ ├── KVM安装配置及使用说明.md
│ └── ...
3. 文档规范
3.1 Markdown规范
咱们在 Linux - 方案教程
里面新建一个 test.md
文件举例:
Linux
├── 方案教程
│ └── test.md
├── 工具使用
│ └── ...
test.md
规范:
文章大标题用 一级标题;
文章各章节用 二级标题;
图片或其他资源,在
public
目录下新建一个文档同名 + _assets 的目录,test_assets 里面放你的图片等资源;MarkDown 文件里面图片资源加载使用相对路径;
Markdown 文件最最开头
标注作者名称,作者的名称可以用花名,也可以用真是姓名,如果姓名大于2个字,取后面两个字,模板如下:
---
Author : mikigo
---
# My Title
多个作者:赵卧龙、钱凤雏、王哪走
---
Author : 卧龙、凤雏、哪走
---
# My Title
4. 启动本地开发效果预览
在项目根目录下,终端输入:
pnpm run dev
即可在本地启动一个在线服务,可以在浏览器中预览效果;