docs: friend links and contribute.md
This commit is contained in:
rand777
parent
302ae7e1d9
commit
5f5d40bc8a
21
README.md
21
README.md
@ -1,27 +1,12 @@
|
||||
# p-guide-docs
|
||||
|
||||
The Site is generated using [vuepress](https://vuepress.vuejs.org/) and [vuepress-theme-plume](https://github.com/pengzhanbo/vuepress-theme-plume)
|
||||
# 项导文档合作开发手册
|
||||
|
||||
## Install
|
||||
项导文档基于vuepress和plume主题进行二次开发，前端使用vue3和vite进行打包开发，后端评论接入项导工作室统一鉴权，兼容重医CAS登录认证。
|
||||
|
||||
```sh
|
||||
pnpm i
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
# start dev server
|
||||
pnpm docs:dev
|
||||
# build for production
|
||||
pnpm docs:build
|
||||
# preview production build in local
|
||||
pnpm docs:preview
|
||||
# update vuepress and theme
|
||||
pnpm vp-update
|
||||
```
|
||||
|
||||
## Documents
|
||||
## 文档
|
||||
|
||||
- [vuepress](https://vuepress.vuejs.org/)
|
||||
- [vuepress-theme-plume](https://theme-plume.vuejs.press/)
|
||||
|
||||
@ -1,10 +0,0 @@
|
||||
|
||||
# 项导文档合作开发手册
|
||||
|
||||
:[tdesign:logo-github-filled]:项目仓库
|
||||
<Repo
|
||||
|
||||
## 文档
|
||||
|
||||
- [vuepress](https://vuepress.vuejs.org/)
|
||||
- [vuepress-theme-plume](https://theme-plume.vuejs.press/)
|
||||
@ -133,12 +133,12 @@ export default defineUserConfig({
|
||||
* markdown enhance
|
||||
* @see https://theme-plume.vuejs.press/config/plugins/markdown-enhance/
|
||||
*/
|
||||
markdownEnhance: {
|
||||
chartjs: true,
|
||||
echarts: true,
|
||||
mermaid: true,
|
||||
flowchart: true,
|
||||
},
|
||||
// markdownEnhance: {
|
||||
// chartjs: true,
|
||||
// echarts: true,
|
||||
// mermaid: true,
|
||||
// flowchart: true,
|
||||
// },
|
||||
|
||||
/**
|
||||
* markdown power
|
||||
|
||||
@ -9,7 +9,20 @@ const campusWiki = defineNoteConfig({
|
||||
const publicService = defineNoteConfig({
|
||||
dir: '公共服务',
|
||||
link: '/public-service/',
|
||||
sidebar: 'auto'
|
||||
sidebar: [
|
||||
{
|
||||
prefix: 'overleaf',
|
||||
icon: 'ep:guide',
|
||||
items: [
|
||||
'LaTeX',
|
||||
{
|
||||
text: '注册',
|
||||
link: 'register',
|
||||
},
|
||||
{ text: '---', link: '---' },
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
|
||||
const CSDIY = defineNoteConfig({
|
||||
|
||||
BIN
docs/.vuepress/public/yuque.png
Normal file
BIN
docs/.vuepress/public/yuque.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
1
docs/.vuepress/public/yuque.svg
Normal file
1
docs/.vuepress/public/yuque.svg
Normal file
@ -0,0 +1 @@
|
||||
<?xml version="1.0" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg t="1739987481816" class="icon" viewBox="0 0 1121 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="4961" xmlns:xlink="http://www.w3.org/1999/xlink" width="218.9453125" height="200"><path d="M1108.01815019 152.23370838l-89.72681904-4.89068759S984.35530601 25.85425236 828.60518734 14.95438794C672.85605155 4.05747208 570.94772487 10.89912728 570.94772487 10.89912728s115.53266578 75.04689342 69.23232192 208.96190045c-34.40189852 72.22708179-88.82848936 131.24065795-146.85822745 199.06356549l-383.7165077 446.83547013c357.19612521-5.34378385 567.78465104-8.01715006 631.76852607-8.01715006 179.43398097 0 331.07773051-158.77731274 324.87296549-335.43767627-4.26657452-121.41308858-42.14974625-148.84556072-55.1715951-202.01999401-13.01693457-53.17541615 13.04248882-137.97419909 96.94294209-168.05153463z" fill="#31CC79" p-id="4962"></path><path d="M491.75514811 420.36840754C303.9413435 636.79804197 8.77812571 981.15119797 8.77812571 981.15119797c531.00326003 142.20833939 775.65656505-202.93110079 813.9672788-322.41582742 51.36204825-160.1985214-21.21001572-238.36892872-62.2835355-263.86222751-139.26272229-86.43818547-242.58930905-4.60369387-268.7067209 25.49329879z" fill="#93E65C" p-id="4963"></path><path d="M494.36266302 415.3735373c29.79329038-32.14919435 131.07848684-106.92875115 266.17881727-22.74130417 41.07745119 25.59355001 113.65344659 104.07945386 62.28746691 264.931574-14.88042808 46.60502898-60.9026239 127.39474547-142.75284119 200.40712857-84.8744628 0.58283314-275.36654789 3.09009681-571.48510096 7.53161958L474.61218731 438.31730962a8405.73366256 8405.73366256 0 0 1 18.93470588-22.06215119z" fill="#60DB69" p-id="4964"></path></svg>
|
||||
|
After Width: | Height: | Size: 1.8 KiB |
@ -13,8 +13,15 @@ config:
|
||||
- theme: brand
|
||||
text: 开始阅读
|
||||
link: /notes/begin
|
||||
icon: icon-park:read-book
|
||||
|
||||
- theme: brand
|
||||
text: 贡献指南
|
||||
link: /notes/contribute
|
||||
icon: tdesign:cooperate-filled
|
||||
|
||||
- theme: alt
|
||||
text: 语雀文档↗
|
||||
text: 语雀文档
|
||||
link: https://www.yuque.com/pguide/public
|
||||
icon: /yuque.svg
|
||||
---
|
||||
|
||||
207
docs/notes/contribute.md
Normal file
207
docs/notes/contribute.md
Normal file
@ -0,0 +1,207 @@
|
||||
---
|
||||
title: 贡献指南
|
||||
createTime: 2025/02/22 16:59:04
|
||||
permalink: /contribute/
|
||||
---
|
||||
|
||||
首先感谢您的无私奉献
|
||||
|
||||
```markdown
|
||||
# VuePress + Plume 主题协作开发手册
|
||||
|
||||
## 前言
|
||||
本手册旨在为使用 VuePress、Plume 主题及 pnpm 进行文档站协作开发的团队提供规范指引，确保开发流程一致性，提高协作效率。
|
||||
|
||||
---
|
||||
|
||||
## 环境准备
|
||||
|
||||
### 开发工具
|
||||
- **Node.js** (v14+)，推荐使用 **[Volta](https://volta.sh/)** 管理版本
|
||||
- **pnpm** (v7+)
|
||||
```bash
|
||||
npm install -g pnpm
|
||||
# 国内用户配置镜像加速
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
```
|
||||
- **Git** (最新稳定版)
|
||||
- **IDE**：VSCode（推荐插件：Volar, ESLint, Prettier）
|
||||
|
||||
### 项目克隆
|
||||
确保团队成员使用 SSH 或 HTTPS 统一方式克隆仓库：
|
||||
```bash
|
||||
git clone [仓库地址]
|
||||
cd [项目目录]
|
||||
pnpm install # 安装依赖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
```bash
|
||||
docs/
|
||||
.vuepress/
|
||||
config.js # VuePress 主配置
|
||||
plume-theme/ # Plume 主题配置
|
||||
components/ # 自定义组件
|
||||
styles/ # 覆盖主题样式
|
||||
public/ # 静态资源（图片、字体等）
|
||||
README.md # 文档首页
|
||||
其他目录/ # 业务文档（按需组织）
|
||||
pnpm-lock.yaml
|
||||
package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 启动开发服务器
|
||||
```bash
|
||||
pnpm docs:dev # 运行后访问 http://localhost:8080
|
||||
```
|
||||
|
||||
### 编写文档
|
||||
- **新增页面**：在 `docs/` 下创建 `.md` 文件，按约定式路由生成路径。
|
||||
- **配置侧边栏**：在 `.vuepress/config.js` 的 `themeConfig.sidebar` 中添加导航。
|
||||
- **遵循Frontmatter**：
|
||||
```markdown
|
||||
---
|
||||
title: 示例页面
|
||||
editLink: false
|
||||
---
|
||||
```
|
||||
|
||||
### 自定义主题
|
||||
1. **覆盖默认样式**
|
||||
在 `.vuepress/plume-theme/styles/palette.scss` 中修改变量：
|
||||
```scss
|
||||
$accent-color: #3eaf7c;
|
||||
```
|
||||
|
||||
2. **扩展主题组件**
|
||||
- 在 `.vuepress/plume-theme/components` 中添加 `.vue` 文件，并自动全局注册。
|
||||
- 使用 `<ClientOnly>` 包裹客户端组件以防 SSR 报错。
|
||||
|
||||
3. **静态资源配置**
|
||||
图片等资源放入 `public/`，通过 `/image.png` 引用。
|
||||
|
||||
---
|
||||
|
||||
## 代码规范
|
||||
|
||||
### 代码检查
|
||||
- **ESLint**: 使用配置的规则检查代码
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
### 提交规范
|
||||
采用 **Conventional Commits** 标准：
|
||||
- `feat`: 新功能
|
||||
- `fix`: Bug 修复
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码格式（空格、分号等）
|
||||
- `refactor`: 代码重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具变更
|
||||
|
||||
**示例**：
|
||||
```bash
|
||||
git commit -m "feat: 添加用户登录功能"
|
||||
```
|
||||
|
||||
**Commitizen辅助**（可选）：
|
||||
```bash
|
||||
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 测试项
|
||||
|
||||
---
|
||||
|
||||
## 部署流程
|
||||
|
||||
### 手动部署
|
||||
```bash
|
||||
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`:
|
||||
```yaml
|
||||
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` 或尝试重新安装：
|
||||
```bash
|
||||
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
|
||||
|
||||
### 参考链接
|
||||
- [VuePress 官方文档](https://v2.vuepress.vuejs.org/)
|
||||
- [Plume 主题配置指南](https://vuepress-theme-plume.rane.wang/)
|
||||
- [pnpm 使用手册](https://pnpm.io/zh/motivation)
|
||||
|
||||
```
|
||||
|
||||
此手册内容兼顾操作流程与最佳实践，助力团队高效协作。可根据实际项目需求调整各项配置参数，保持定期更新维护。
|
||||
@ -25,20 +25,21 @@ groups:
|
||||
location: Global distribution
|
||||
organization: PGuide Studio Art
|
||||
desc: Creative creates create creations.
|
||||
- title: 重庆医科大学信息中心
|
||||
desc: CQMU Center Network
|
||||
list:
|
||||
- name: 二级门户
|
||||
link:
|
||||
- title: MED Explorers+
|
||||
desc: A research team affiliated to the College of Basic Medical Science composed of undergraduates
|
||||
list:
|
||||
- name: 官网
|
||||
link: http://117.72.14.208/
|
||||
avatar:
|
||||
location: 中国，重庆沙坪坝
|
||||
organization: VuePress
|
||||
desc: 即使慢，驰而不息，纵会落后，纵会失败，但必须能够到达他所向的目标。
|
||||
socials:
|
||||
- icon: github
|
||||
link: https://github.com/pengzhanbo
|
||||
- icon: twitter
|
||||
link: https://twitter.com/pengzhanbo
|
||||
link: https://medseek.site/
|
||||
avatar: https://www.medseek.site/wp-content/uploads/2025/02/cropped-logo.png
|
||||
location: 重庆医科大学
|
||||
organization: Med Explorers+
|
||||
desc: A research team affiliated to the College of Basic Medical Science composed of undergraduates
|
||||
|
||||
- title: 西湖大学超算中心
|
||||
desc: HPC Base for computation in WLU.
|
||||
- title: 中国科学院大学北京物理高能研究所
|
||||
@ -46,8 +47,7 @@ groups:
|
||||
desc: visit https://www.cernet.net for more information
|
||||
- title: 奇安信网神（北京）信息科技有限公司
|
||||
desc: 网络安全领军者
|
||||
- title: CQMUA
|
||||
desc: 重庆市Minecraft高校联盟，https://3w.cqmua.cn
|
||||
|
||||
- title: MUA
|
||||
desc: 中国大学生Minecraft高校联盟, https://www.mualliance.cn
|
||||
- title: 上海交通大学Minecraft社
|
||||
|
||||
@ -192,4 +192,3 @@ list:
|
||||
# color:
|
||||
# nameColor:
|
||||
---
|
||||
1234
|
||||
@ -8,3 +8,4 @@ permalink: /public-service/overleaf/
|
||||
- 外网地址（暂未开通）：https://latex.cqmu.edu.cn/login
|
||||
- 上交大地址：https://latex.sjtu.edu.cn/login
|
||||
## LaTeX
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user