From 5f5d40bc8a07610a14f93bb57488012531598704 Mon Sep 17 00:00:00 2001 From: rand777 Date: Sat, 22 Feb 2025 17:17:12 +0800 Subject: [PATCH] docs: friend links and contribute.md --- README.md | 21 +- README.zh-CN.md | 10 - docs/.vuepress/config.ts | 12 +- docs/.vuepress/notes.ts | 15 +- docs/.vuepress/public/yuque.png | Bin 0 -> 4448 bytes docs/.vuepress/public/yuque.svg | 1 + docs/README.md | 11 +- docs/notes/contribute.md | 207 ++++++++++++++++++ docs/notes/friends-organizations.md | 24 +- docs/notes/friends-persons.md | 1 - docs/notes/公共服务/Overleaf在线协作企业版.md | 3 +- 11 files changed, 254 insertions(+), 51 deletions(-) delete mode 100644 README.zh-CN.md create mode 100644 docs/.vuepress/public/yuque.png create mode 100644 docs/.vuepress/public/yuque.svg create mode 100644 docs/notes/contribute.md diff --git a/README.md b/README.md index 2e9349d..b89b88b 100644 --- a/README.md +++ b/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/) diff --git a/README.zh-CN.md b/README.zh-CN.md deleted file mode 100644 index 05f92ff..0000000 --- a/README.zh-CN.md +++ /dev/null @@ -1,10 +0,0 @@ - -# 项导文档合作开发手册 - -:[tdesign:logo-github-filled]:项目仓库 -@004kYjP>u*#u?i6`8*@- z?%J6iL>qvCca8J_Rf7Vn000M{iN3B?C~Wi1oS%~sZ})SqkeW#qkA>ELGi2{={txad_D2f{q&p8R$vf-<-cwr1qPy zj@jHKO+5IxPW#r-GI|Vk>`zPYqN8mmjmW%9{3;w@0x@)5KO%Jkn~kl#GZ^%VKf)emd!G)^ zl(=~0zER+oBdUQ0Lt_J))lSBn4ACd+Q)0x4dqtrvq5vleUdtFJ%A%`DX$dp1fmu_< z#D4yKWD_$bF5chiDd)MWH&+dh^KDUU;FT{x7ioJkmW?wjD z5p3V@;s*+_9&%Ro@?x{1cHgnKYv9|QiC|N4$nWpJ-tiz3ud~<7{2s8RFjoJ1c@d#b z{PExS_8j&7p)n&~AEAi#Ig`b8y8aI{OS#VvwG{y<#4FxM>FEc4*h}{|mfz=Vs(zEU zM-OD~rp}N80-XKxe=x%XHCG~)Lsm9j*p&v8mpyiGx)6c&aq+Okt-|ra9QLmOZ1D6V zGu}0Ws|R@a03zwU^$p!y)_+rJSsua+y@}s0 zi%@OkFA#+@4rFMOIW^G9D*%UHRJklRm*yLO#`v!e?Y)xb8>G%m8GS0VEI}9C-#jn{ z!i%x+Z)MJ^@3eNYPs>9Aj^%jVO%R%XOZKQixdo^~%qXR6aj8%F*Qq&v!R7H2iHM^X zmw?&uCe3GSg!<`6W_mS?;d|ixTR?4-$!YdkSGNV!L(bSNu5-dKS(ke(`-{{D=)FUJuz;e??e`j`#ZN~-J;mS<{ zIk{v2HkWFd*}ZAMyNcBam?$lAy`FWvTo5nKAYaidiF*tMS4OM9f!gvBaw1H3x`e_8 z?!+ei5(cfh!pAQ^`7MWw&gGV`kX#1gC3`bM#b*5>HvwiXFS4eV0xvp)1mG3#`n#h* z6CDn+MWs)diy!BhIi6-sjR$fVm_vlfW9KO2bYU-T_6SX*>3SF{%AmKvisRZnn7QlPa0E7vR@0~v&jUj z5&Uf>tc8F#mQ1+*?>XO;h=7f)h`8k=WS;i{+QqZn_TvizZ>*|ZKbrc-Bd!dt@feY2hycSay7Iegcz$hDLn@@ls(l~0QSIYYxc>&pgV9%l@Xi}hTeE07*OO`q5Nn2?oHe; z2%I4$XyCH~0Irn5PI#g*=w9P=JTV`3(v~%~Rab1CFm`6MW}@>3QerI(E`*aNs)|>he44MtrsmzR*eS`S0AJsPOGKEA62$s@9t=8Zhhmdb$ri z-pSE(E{;bCow-+AeRDRiwHsCMG@s=DYe*9`rAi&I>;|g(*tajhSTBeK7Bz*t6wKhX zpQTLunIdVzQTIf~yK24+&EXJ7f`wf#xz;ZK=cyqztj-8P0oi81+jid^Ol%j>vBiWG zqKK;zq8xZ$Ay@z~T2U$LLCP4g$>HJaEfEVE&qV5A6udXQC^ z$X3(JbmaYV&Uw4FlJzemryWL*X)mpelJwisAyLfs)6Z90_f|hDTE|F9{~ggMBGe;` zZH>-abCEakvt}Q@x#!J!m~#>l53|G{?69smXtJvQzMpFZtYuH9Q|Z(dc4Py0G`iJj zq}8U1!Y>J3>JoF^VTF=qKdTk5-f&5;;L^EoZ^VhWH|B#xsaq!h6_+F3Pd8S7g*Nwf z+J}IWJ4*DOS@oOK&!N0mC#r+o5D`_RRfQAdRfB{_l2f@F0n`GodU-;k6uDRc5~U?9 zq7_JwdVD{#8kFn;Bls%2IhpnepxhB-0uuN`WrkU+6Pvj0ymWO6BZ|+R0o)NE>Ret` z<+)#d6p4s+NM)ozSZA5plNTz7Ntxf~Q#X7$vs;Yi36iOqBiS`GUvfzyoE4#MvgKsn zk_O+NAa_MLK~pjB4R1?(*VH6LHO=YpGJ69MOLApNUMOnR-_NVvY_Hl3& zZd5Z8&6Bo!4S!U^suxRXQr0bcy04VX0^i1VvHt*Gef_-hG^9`m=0 zTQ35@p%He(#Sm41TP!H##bp8h?=(ljdk~ylJ^%P^6)t$1b*1RC>rTty)6VG z?O5~M2a1MKXicIdozhZN^x(7i`5Kcinl?NRQ20a7_{5Xizfv-f_tLzyT_oCEpuvb( zlAn;^6!@}4PU_M}suc9IhifcJE;;68S0P(Ov09H(=@jtA*zTCxX?b6`sO98!#*5wo z6fLZNvOlMyUU#B3s9cvn2mI;5sf`vj$C#q2wpeZ zpMJP3=E12nBZqu`c5GO2T08eGW<`VLQ$YKBLL5Yk#xUrj|2@^BJ!PCdZXe&d7($P+ zkgl;iZ6-LB(P&l2qFb74Ai|zPC9Ch@k|0jI<1P5eeMvCS=%-4XzU<8c0 zrNjP}IfJ}S1?7tud)n!sI2LCZ#iv6!1#BiKbi+9jOjCrfxc45}SirdWz41O{uN>m` z@hPIhuYW8{mypDw|BG5lJ1c}ohNyjg7w2e9TvSM|>D8A?8nh$TFoPSztmMfn2{0=w znj}2tK6cA)hw%75sI8}UDr0@uVn;x=N}yb|m4_VX@`=>NCuF(bZojop;6MDdZ&2oU|!wG%y zbnNg=)C%7Ry&gDHMN_s|qyJ=5dbTHeXq$Gz$+tm-3K&@VAyH?pj+ClRAz@4G~5Grj5j-7d+|cqdShCY?&cJHr{Y53*>Ae}66MgR&ne9dmWD@g zI4yB$^}qTUn{NjOAQQY)V$d||Ud>$)p2e`7?GyV3v#@6%aC8M(F!5Ip<uC_zfSTvYvR;9J9?y~UuqXkJCOk0Yj2q;_|>f=8s;g-`| zpS;CJGv2VfrQvG3PI8#|9vzLTAI3{{!+n*)i1Fkp$&Xl#p)#D~BL1OSezO1t4JL_s zF~AKDc3I5h{Dq3&TIrE+A8Bd$kG+#S0O){ZEQa`{bIT)tq7JKq{Mnd;KF72zz&~Nt zi^VNfGFhAksWcu>yMJfskxSbn=_ZztujEiTuF zCcoI0Wp`o7(ConlM|;C9#7;6>DJ-^Z5>TE-fmhbdeIeJ*$9Bw%bpJtbUopDwn(;;1 zBJ!k8_{#%P{&_W2HSA_^x?0=I%Ay^ZnhqiNMlqgy(EW7-Lgs+?o4GV`wZF{B1uK6A zyi+d)XH!9gSBKrMKUyRDq!@<_SvRC~QrGI-NuxVnR<`;6NcA0YchtFpCjN7VaC)yT zPDGJd_tDd|=k3~V|NqJsfM&L}BmQV2QFg5+>HFn?jFkDM$(YU8>o)}vx%meZ;nyL> zI>n@Nks+bRtNsY_OJGj}?mO|cAeDXsrpL})*5Ty3Sqc29kT9G0s7Mzh4v$GN_Uypy z_cIP}NRW(Kvj#Aqy%ZC!qx=QU`~1Yf2qo#-HKx}wpn_FaUnM#uY6;17YFExA`(SNZ zqh6jSwR4GKt5z;H(Px?P_9Ch}Ds+Q1)Nc8>8)-BWY|DW6z<9y;<7l~kF?G&E_r2$V z#U=~C4y$Z28q%1a5aMM-+b_w^Tk2-jxhPTKlHSHr7BaSuW5mFun*!?WrccyEk|T%)sTGkezz^<1M*@d z<*TNKx$ev_yJAy%Le{;xHkDwZdfO^3tuG0n$D8I&{7mrWLBFAjaQM(f-nW21f(jaa ziR^U5JiaZv0=sKJ?1MR!vYO*P%O!)En7>{c3}cedO=N~51x?z zaw%DCW@ZEzNS(4x${T3*!wA-t;C1i6^H6VGOFju>Ok%a1cmg?f(rG$f=vRBYnfZ#- zr^7z!;rywD#KaOWR$3c5UgUjAC;N(1LcKN64__u)1o&{Tn%*1OYf%Gup43H&FJj)fXQe7c8qu2ZyMCIAxy3;ilRc+CF*#T=jK literal 0 HcmV?d00001 diff --git a/docs/.vuepress/public/yuque.svg b/docs/.vuepress/public/yuque.svg new file mode 100644 index 0000000..85d74fd --- /dev/null +++ b/docs/.vuepress/public/yuque.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index afa70e6..68550c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 --- diff --git a/docs/notes/contribute.md b/docs/notes/contribute.md new file mode 100644 index 0000000..97a5cc4 --- /dev/null +++ b/docs/notes/contribute.md @@ -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` 文件，并自动全局注册。 + - 使用 `` 包裹客户端组件以防 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) + +``` + +此手册内容兼顾操作流程与最佳实践，助力团队高效协作。可根据实际项目需求调整各项配置参数，保持定期更新维护。 \ No newline at end of file diff --git a/docs/notes/friends-organizations.md b/docs/notes/friends-organizations.md index 1b5b7a1..be7ba51 100644 --- a/docs/notes/friends-organizations.md +++ b/docs/notes/friends-organizations.md @@ -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社 diff --git a/docs/notes/friends-persons.md b/docs/notes/friends-persons.md index 228c63d..2f89040 100644 --- a/docs/notes/friends-persons.md +++ b/docs/notes/friends-persons.md @@ -192,4 +192,3 @@ list: # color: # nameColor: --- -1234 \ No newline at end of file diff --git a/docs/notes/公共服务/Overleaf在线协作企业版.md b/docs/notes/公共服务/Overleaf在线协作企业版.md index 8b17bb1..dfaf567 100644 --- a/docs/notes/公共服务/Overleaf在线协作企业版.md +++ b/docs/notes/公共服务/Overleaf在线协作企业版.md @@ -7,4 +7,5 @@ permalink: /public-service/overleaf/ - 内网地址：http://192.168.183.171/ - 外网地址（暂未开通）：https://latex.cqmu.edu.cn/login - 上交大地址：https://latex.sjtu.edu.cn/login -## LaTeX \ No newline at end of file +## LaTeX +