PGuide-Docs/contribute.md at 0ed005779c4326fb0f58c724904795fe05ea1d8d

rand777 0ed005779c docs: contribute.md

2025-03-10 00:08:44 +08:00

9.1 KiB

Raw Blame History

title	createTime	permalink
贡献与开发指南	2025/02/22 16:59:04	/contribute/

首先感谢您的无私奉献，项导文档基于Vuepress的plume主题构建，由多名成员共同维护，内容完全开源。

我是文档的编写者

项导文档使用markdown语法进行编写，首先得大概掌握下markdown基础语法

在您完成markdown类型文档编写后可以

通过github创建合并请求
email到我们的邮箱
QQ发送给 rand777

我想直接写一篇文档

不想这样麻烦也可以的，联系rand777并获取语雀编辑权限，或将word文档/PDF文档/PPT发送给rand777

其他注意事项

请参考文档编写规范

我是文档站的开发者

在参与合作开发之前，需要您学习一些基础知识:

随后，联系 rand777 加入项导文档加入github开发组。

:::tip 联系格式正文写明你是谁，想要编写哪部分，从哪里知道项导文档的（比如网上看到的-具体途径，熟人推荐-哪位熟人）。 :::

配置开发环境

:::info 开发环境这里假设你的电脑是windows10或11的操作系统 :::

:::steps

下载WebStorm

这个软件是咱们主要写代码的地方，软件本身用于前端开发，您可以在这里详细了解。其他同类型的开发软件，如VSCode，也可以。

请先完成学生邮箱申请并申请JetBrains教育版

下载可以到 WebStorm官方网站或 Alist动态开源软件镜像站下载

下载NVM

我们在进行开发的时候，需要一个服务端来支撑web应用的运行，Node.js是目前非常流行的开源web服务器运行时环境。在运行不同的前端项目时，往往需要的node.js版本是不一样的，而 NVM（全名：Node.js Version Manager）可以帮助我们更高效地管理不同的node.js版本和依赖环境。

软件安装及应用教程看这里

安装完成后记得重启IDE和终端

导入项目

打开WebStorm后，你可以

使用HTTPS协议导入

git clone https://github.com/MultipledMe/PGuide-Docs.git

也可以使用SSH协议导入，需要配置SSH和github设置

git clone git@github.com:MultipledMe/PGuide-Docs.git

安装项目依赖

安装 pnpm

在WebStorm终端中输入

npm install -g pnpm

安装好后，再输入

pnpm install

这样就完成了项目依赖的安装

启动本地开发环境

终端中输入

pnpm run docs:dev

打开http://localhost:8080即可访问本地的开发环境了。代码修改时，内容也会一起跟着改。

项目设置

将 .cache .temp .public 文件夹设置为排除

阅读开发规范章

请合作开发者依次阅读 Git规范、静态资源管理规范、文档编写规范、其他注意事项、常见问题及解决方案

:::

Git规范

项导文档开发Git规范采用 :[logos:angular-icon]:Angular 规范

合并请求

文档编写规范

俗话说，无规矩，不成方圆。一个优秀的团队离不开统一的规范，项导文档开发也是如此。

静态资源管理规范

这里是为了规范您的图片、视频、PDF、矢量图引用方法，Plume Vuepress推荐你引用静态资源的方式如下：

:::info 静态资源类型、大小规范

图片文件：70%分辨率jpg或png图片，放入 PGuide-Docs/.docs/.vuepress/public/
视频文件：.mp4文件，帧率16/24FPS
PDF文件：请尽量精简，不需要的页面不上传 :::

截图工具设置

::: steps

下载pixpin

前往

:::

对象存储

所有PDF、.mp4视频放在项导腾讯云对象存储上，如有此类文件，将其发送给 rand777，链接处留空，并留下以下格式的TODO

今天天气多么好呀，于是我打开了书这里==需要PDF文件==

然后写上TODO: 需要{文件名.pdf}，并ctrl+/注释，在代码里看起来是这样的：

高数，即高等数学，比初等数学高一些。教材如下：
#TODO: 需要高等数学.pdf

项目结构

::: file-tree

docs
- .vuepress
  - .cache #缓存文件夹
  - .temp #临时文件夹
  - public #静态资源文件夹
    - avatar #头像文件夹
    - src #图片文件夹
    - *.svg #矢量图标
  - theme #主题设置文件夹
    - style #主题自定义文件夹
      - custom.css #自定义主题
    - shim.d.ts #自定义vue组件导入
  - client.ts #客户端配置
  - config.ts #全局功能配置
  - navbar.ts #导航栏配置
  - notes.ts #笔记配置
  - plume.config.ts #主题选项配置
- notes
  - CS-DIY #计算机自学指南
  - 公共服务 #项导公开的服务
  - 后台管理 #后台管理界面
  - 大学百科 #大学百科全书
  - 学习笔记
  - 项目文档 #包含项目的介绍、人员等
  - begin.md #“开始阅读”页
  - contribute.md #“贡献”页
  - friends-organizations #友情链接-组织页
  - friends-persons #友情链接-个人页
  - friends-quotes #友情链接-常见问题页
  - Templates.md #Vuepress Plume模板页
- README.md
.gitattributes #git属性设置
.gitignore #不进行git的文件(夹)
.npmrc #npm包管理设置
package.json #所有npm包依赖
pnpm-lock.yaml #所有pnpm包依赖
README.md #中文项导文档介绍
README-en.md #英文项导文档介绍
… :::

🆘 常见问题及解决方案

遇到git推送异常？（SSL ERROR）

🌐 检查您的星际通讯器（Clash代理）及允许局域网是否开启

2. 🛠️ 配置Git直通车（本地代理）：

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

🚀 尝试乘坐SSH穿梭机：

git clone git@github.com:MultipledMe/PGuide-Docs.git

🧐 真理之门异常？

当看到奇怪的Giscus错误提示时不用惊慌，这是跨域资源请求的小精灵在调皮，对我们的文档城堡没有影响：

开发流程

启动开发服务器

pnpm docs:dev  # 运行后访问 http://localhost:8080

编写文档

新增页面：在 docs/ 下创建 .md 文件，按约定式路由生成路径。

遵循Frontmatter：

---
title: 示例页面
editLink: false
permalink: /../../
---

代码规范

提交规范

采用 Conventional Commits 标准：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式（空格、分号等）
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/工具变更

示例：

git commit -m "feat: 添加用户登录功能"

Commitizen辅助（可选）：

pnpm commit  # 启动交互式提交

分支策略

Git Flow

分支类型	描述	命名示例
`main`	稳定生产版本	-
`dev`	集成分支，功能合并测试	-
`feat/*`	功能开发分支	`feat/user-auth`
`fix/*`	Bug 修复分支	`fix/mobile-layout`
`chore/*`	配置/工具调整	`chore/eslint-config`

合并要求：

通过 Pull Request 合并到 dev
至少一个团队成员 Code Review
通过所有 CI 测试项

附录

参考链接


此手册内容兼顾操作流程与最佳实践，助力团队高效协作。可根据实际项目需求调整各项配置参数，保持定期更新维护。

9.1 KiB Raw Blame History Unescape Escape