From f385554ef7ec891dfac35407f54e50ddb7a4568c Mon Sep 17 00:00:00 2001 From: cyan4run Date: Tue, 23 Apr 2024 00:23:37 +0800 Subject: [PATCH] fix toc and add git use --- docs/manual.md | 168 ++++++++++++++++++++++++++++++++++++++++++++--- docs/template.md | 7 +- 2 files changed, 163 insertions(+), 12 deletions(-) diff --git a/docs/manual.md b/docs/manual.md index 5374039..8e5e384 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -1,4 +1,4 @@ -# 项目结构介绍 +## 项目结构介绍 ``` -|-.github/workflows #这里存储github page部署yml -|-docs #这个目录用于存储所有文档内容 @@ -11,7 +11,7 @@ -|-mkdocs.yml #网站的配置文件，具体内容看下文 -|-requirments.txt #Python的需求文件，如无必要，勿增实体 ``` -# 新增内容说明 +## 新增内容说明 如果需要新增板块和页面，请对 `mkdocs.yml` 的 `nav` 板块下进行修改 下图是新增一个通识课 general 的样例 ![image.png](https://cdn.jsdelivr.net/gh/wandering-the-earth/blog-img//blog/202404221020821.png) @@ -22,10 +22,13 @@ ![image.png](https://cdn.jsdelivr.net/gh/wandering-the-earth/blog-img//blog/202404221025576.png) `general` 目录对应新增的核心课的所有内容，一个版块一个目录，方便维护，下面是`general` 目录的内容 ![image.png](https://cdn.jsdelivr.net/gh/wandering-the-earth/blog-img//blog/202404221029520.png) -# 贡献指南 +## 贡献指南 本网站欢迎一切贡献 不过课程内容只面向HITWH的课程内容范围，如果你想要为本网站进行贡献，以下是一些指南。 -## 本地构建 + +> 可以先看下文git的使用，以熟悉git的操作 + +### 本地构建 项目拉取： ```sh git clone https://github.com/Fifth-Space/HITWH-CS.git @@ -49,7 +52,7 @@ mkdocs serve - 之后即可通过浏览器访问 localhost:8000 预览网站 -# 贡献守则 +## 贡献守则 - 对于课程请进行客观的评价，尽量不要带有主观色彩 - 对于外部资源，请尽量插入链接，不要将文件传入本 repo - 尽量不要上传有版权的文件，例如课件等 @@ -58,26 +61,171 @@ mkdocs serve - 也可以将文件上传到对应课程文件夹中，并插入相对链接 - 尽量规范编写 markdown，避免出现格式错误，**先在自己的本地进行测试！** -# 贡献方式 +## 贡献方式 通过 PR（即 Pull Request）的形式来进行贡献，具体流程： - 在 GitHub 网页端点击右上角的 fork，将本仓库 fork 到自己的账号下 -- 在自己账号的对应仓库中进行修改 +- 在自己账号的对应仓库中进行修改（提交方式参见git使用） - 修改完成后，在自己的仓库内Pull requests中 点击 New pull request，提交一个 PR - ![image.png](https://cdn.jsdelivr.net/gh/wandering-the-earth/blog-img//blog/202404221056918.png) - ![image.png](https://cdn.jsdelivr.net/gh/wandering-the-earth/blog-img//blog/202404221057922.png) - 等待管理员的审核、修改，然后合并到本 repo 中 -# 项目规划 +## 项目规划 ``` general: 通识课 -outer: 外专业选修课 basic: 数理基础课 culture：文化素质课 major：CS 专业类课程 labs：学校各个实验室的技术栈介绍和项目（包括老师的实验室） -competition: 计算机相关的各个比赛的介绍 salon：俱乐部可公开的分享会文档 CTF-WP：俱乐部参加的CTF比赛题解 ``` + +## 有关Git的使用 + +### git下载 + +官网下载 https://git-scm.com/ + +安装完打开bash输入 `git`即可查看是否正常 + +### git和github和gitee的关系 + +git是管理代码的工具，可以记录源码的历史，本地 + +github和gitee都是托管仓库，在线 + +使用git可以方便的推送代码到远程仓库，也可以方便的进行**多人协作** + +### Git的配置 + +首先，要配置电脑的ssh key + +打开bash/cmd/powershell + +```bash +ssh-keygen -t rsa -C "" +``` + +这个email应该对应你的github/gitee邮箱，事实上两个托管平台用一样的就行（事实上`-C`参数可以不添加 + +敲三次回车一路到底就行（可以输入文件名/密码，但是不是必要的） + +这时候会在你的用户目录下的.ssh文件夹里生成一个id_rsa （私钥） id_rsa.pub（公钥），我们使用公钥 + +```bash +cat .ssh/id_rsa.pub +``` + +获取命令行输出的公钥内容，全部复制 + +登陆github，进入到个人的Settings + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404230003183.png) + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404230005376.png) + +添加sshkey，直接粘贴刚刚的公钥就行，确认。 + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404230007096.png) + +没什么问题的话一封邮件会发到你的邮箱告知你添加了这个公钥。现在，理论上你这台电脑就能连接到github了 + +```bash +ssh -T git@github.com +``` + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222337770.png) + +> 如果换台电脑，同样的流程也得走一遍 + +接下来配置git + +还是在命令行（推荐用git的bash） + +```bash +git config --global user.name "your_github_username" +git config --global user.email "your_email" +``` + +其中用户名是你注册github的**账号名字** + +邮箱是注册使用的**邮箱**，没什么问题就和上面公钥用的一样 + +```bash +git config --global --list +``` + +可以看到自己的配置 + +### 如何连接远程 + +#### 本地项目到远程 + +在github中新建一个仓库，什么都不添加 + +```bash +git init #初始化git 生成一个.git文件夹在当前目录,默认创建master分支 +git add . #添加文件到暂存区，.代表所有文件 +git commit -m "your commit" +git remote add origin #建议使用ssh url,原因下面有讲 +git push -u origin master #推送远程，以后用git push就行 +``` + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222338011.png) + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222338838.png) + +这样在github页面上你应该能看到你的添加的文件了 + +#### 远程项目到本地工作 + +```bash +git clone +cd example #进入项目文件夹 +git pull #每次开启你的工作前，检查是否是最新的 +git checkout master #切换到master分支 在我们的站点 这个分支是main +git add . #添加文件到暂存区，.代表所有文件 +git commit -m "your commit" +``` + +以上操作都是正常操作 + +但是这时候推送，可能会遇到这样的问题： + +鉴权失败：github移除了密码验证 + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222338241.png) + +这个时候实际上就是上文要使用ssh的问题 + +解决办法如下 + +```bash +git remote -v #可以看到的确git remote现在是http url 因为clone用的http +git remote rm origin +git reamote add origin git@github.com:cyan4run/example.git #添加ssh的远程 +git remote -v #检查一下 +``` + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222338887.png) + +然后愉快的推送到仓库 + +```bash +git push -u origin master #master是连接的远程分支，而在我们的站点中，这个分支是main +git push #第一次推送以后以后可以用这个 +``` + +![](https://cdn.jsdelivr.net/gh/cyan4run/cdn_img/img/202404222339907.png) + +另外的解决办法是，用token替代你的密码，不介绍了，去setting添加就行 + +### 关于多人协作 + +将多人协作fork到自己的账号仓库下以后，操作和 **远程项目到本地工作** 相同，参见上文 + +推送到自己的仓库以后，请提交pull request等待多人协作仓库管理员的审核，即可合并到主分支完成一次贡献 + diff --git a/docs/template.md b/docs/template.md index 8caea03..2e6fce8 100644 --- a/docs/template.md +++ b/docs/template.md @@ -6,6 +6,9 @@ SE <专业基础/专业必修/专业选修> 紫丁香 <专业基础/专业必修/专业选修> +> 请注意目录结构。 +> +> 要想在右侧渲染出目录 必须仅有一个一级标题或者从二级标题往下书写 ## 课程学习内容 @@ -31,9 +34,9 @@ === "<教师1>" <授课方式（如是否双语、板书/PPT/其他）、授课水平、给分情况等> - + === "<教师2>" - + <授课方式（如是否双语、板书/PPT/其他）、授课水平、给分情况等> ``` 注意教师左右的引号，以及段落内容要全部缩进 4 空格。