PGuide-Docs/contribute.md at e8297e17fd8909ff0a55229da72874eb7f056a7c

rand777 e8297e17fd refactor: contribute.md

2025-03-09 06:15:31 +08:00

10 KiB

Raw Blame History

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

首先感谢您的无私奉献，项导文档基于Vuepress的plume主题构建，由多名成员共同维护，内容完全开源免费，并且承诺保障时效性和准确性。

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

我是文档站的开发者

随后，联系 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版本和依赖环境。

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

安装完成

:::

我是文档的编写者

markdown基础语法
VuePress markdown拓展语法
合并请求的创建（也可以联系文档管理员）

我想直接写一篇文档

也可以的，联系rand777并获取语雀编辑权限

文档编写规范

俗话说，无规矩，不成方圆。一个优秀的团队离不开统一的规范，

静态资源规范

这里是为了规范您的图片引用方法

截图工具

对象存储

下载pixpin

分支管理

项目克隆

这一步参考 README.md

项目结构

::: file-tree

docs
- .vuepress
  - config.ts
  - client.ts #客户端配置
  - navbar.ts #导航栏配置
  - notes.ts #笔记配置
- page1.md
- README.md
theme 一个主题目录
- client
  - components
    - Navbar.vue
  - composables
    - useNavbar.ts
  - styles
    - navbar.css
  - config.ts
- node/
package.json
pnpm-lock.yaml
.gitignore
README.md
… :::

🛠️ 开发工具箱

基础设施

Node.js v18.20.0+（推荐使用Node版本管理器）
包管理器：pnpm 8+ 或 Yarn 2+（需要现代项目管理体验）

📂 核心档案库

项导文档/
├── docs/                    # 故事书页（网站内容存档）
└── .vuepress/              # 魔法工坊
    ├── public/              # 百宝箱（图片/字体等静态资源）
    ├── theme/               # 城堡装修图纸（主题配置）
    ├── client.ts           # 接待员（客户端选项）
    ├── config.ts           # 百科全书（全局配置）
    ├── navbar.ts           # 指路牌（导航栏配置）
    ├── notes.ts            # 藏宝图（文档结构导航）
    └── plume.config.ts     # 调色盘（主题样式配置）

🎬 快速启航指南

🏗️ 搭建脚手架

# 零基础同学建议安装nvm
nvm install lts

# 选择镜像源（顺风车时间）
nvm node_mirror https://mirrors.cernet.edu.cn/nodejs-release/  # 校园专线
nvm node_mirror https://mirrors.aliyun.com/nodejs-release/     # 阿里云快车

# 装备新时代工具箱
npm install -g pnpm  # 速度更快的npm替代品
pnpm i              # 一键安装所有魔法原料
pnpm run docs:dev   # 打开传送门进本地预览

✨ 热更新小技巧

修改导航栏配置后记得Ctrl+C重启服务，看到"VuePress dev server listening"才算开启新世界大门哦~

🌉 开发分支规范

代码地铁乘坐指南

在本地开设dev/[你的名字]新线路
完成精彩修改后：（快捷操作指南）
- Ctrl+Shift+K 召唤提交魔法阵
推荐消息格式：（让代码会说话，代码规范为 Angular Commit）
```
docs: README新增星空导航
fix: 修复404星际迷航问题
feat: 新增宇宙超链接模块
```
前往Github站台点击「New pull request」提交专属班列

📍 避坑手册精选

资源位面法则

🎨 所有矢量图请存入/public/*，引用时直接/AI.svg即可
📹 视频资源统一放在src/video，播放代码示范：
🔍 遇到奇怪报错时，尝试这个重启秘籍：
```
pnpm update && pnpm upgrade
```

神秘配方

<!-- Pixpin截图魔法 -->
![配置示例1](public/src/星空配置图1.png)
![配置示例2](public/src/星空配置图2.png)
*按F2即可完成星际截图归档*

🆘 常见问题

遇到git推送异常？（错误类型：SSL ERROR）

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

🛠️ 配置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: /../../
---

自定义主题

覆盖默认样式
在 .vuepress/plume-theme/styles/palette.scss 中修改变量：
```
$accent-color: #3eaf7c;
```
扩展主题组件
- 在 .vuepress/plume-theme/components 中添加 .vue 文件，并自动全局注册。
- 使用 <ClientOnly> 包裹客户端组件以防 SSR 报错。
静态资源配置
图片等资源放入 public/，通过 /image.png 引用。

代码规范

代码检查

ESLint: 使用配置的规则检查代码
```
pnpm lint
```

提交规范

采用 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 测试项

部署流程

手动部署

pnpm docs:build        # 构建
pnpm docs:build:clean  # 清理并构建
# 部署到 GitHub Pages：
git subtree push --prefix docs/.vuepress/dist origin gh-pages

自动化（GitHub Actions）

创建 .github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with: { node-version: 18 }
      - run: pnpm install
      - run: pnpm docs:build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vuepress/dist

常见问题（QA）

Q1：本地样式未生效？

检查浏览器缓存，尝试 Ctrl + F5 强制刷新。
确认样式文件未被缓存，服务端需配置无缓存策略。

Q2：pnpm install 报错？

清空 node_modules 或尝试重新安装：

rm -rf node_modules
pnpm install --frozen-lockfile

Q3：Plume主题自定义无效？

确认配置文件路径正确：.vuepress/plume-theme/。
检查浏览器控制台是否有 Vue 报错（如组件未注册）。

附录

技术栈版本

VuePress: 2.0.0-beta.60
Plume 主题：1.5.0
pnpm: 8.7.6

参考链接


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

10 KiB Raw Blame History Unescape Escape