贡献指南

贡献流程

贡献指南是关于 CSBAOYAN2025 相关内容的贡献指南，其中指引不同技术水平的撰写者完成对于 CSBAOYAN2025 内容的贡献。

本部分将讲解详细的贡献流程，其中包括的前置技能有 Git 的使用以及 Markdown 的撰写。相关技能的初步了解可以前往廖雪峰的 Git 教程以及 Markdown 官方教程进行学习。

注册 Github 账号

作为贡献者，首先需要注册 Github 账号，这一步十分的简单，前往 Github 官网并点击 Sign Up，根据要求进行注册即可，在这里并不进行过多的讲解。

初始化本地 Git 并配置 SSH

在 Git 官网选择下载 Windows 版本并按照提示进行安装。

alt text

在安装中需要注意的是：

在 Select Components 中选择 Git LFS，按需求安装其他组件。
在 Adjusting the name of the initial branch in new repositories 中可以选择 Override the default branch name for new repositories 并将主分支命名为 main（貌似是因为原默认名称 master 涉及种族歧视，如今 Github 默认分支为 main，最好保持一致）。
在 Adjusting your PATH environment 中选择 Recommended 的选项。
其他内容选择默认选项即可，或者在互联网进行查询。

安装之后首先设置 Git 的基本信息：

git config --global user.name "Your Name"
git config --global user.email "Your Email"

之后需要配置 SSH，首先需要检查是否已经存在 SSH 密钥，如果存在则跳过此步骤，否则需要进行创建：

ssh-keygen -t ed25519 -C "Your Email"
# 或者使用 ssh-keygen -t rsa -C "Your Email"
cat ~/.ssh/id_ed25519.pub
# cat ~/.ssh/id_rsa.pub

将生成的密钥复制到 Github 中的 Settings 中的 SSH and GPG keys 中的 New SSH key 并粘贴。

此时本地理论上已经可以进行 Git 的 push 等操作到远程储存库了。

Fork 本仓库

进入本仓库的 Github 主页，点击 Fork 按钮，即可将本仓库 Fork 到自己的 Github 账号下。

alt text

Fork 操作本质上是复制了一份本仓库到自己的账号下，并在自己的账号下享有修改的权限，同时可以比较自己账号下的仓库与上游仓库之间的更改差别，Fork后的仓库可以在自己账号的 Repositories 中看到。

alt text

克隆仓库

在 Fork 完成之后，在自己 Fork 的仓库中，找到并点击 < > Code 按钮，之后点击 SSH 按钮，并复制链接。

alt text

在本地找到适合保存本项目的文件夹，右键资源管理器，点击 在终端中打开，并进行克隆操作。

git clone your_ssh

对于之前没有运行过 git clone 或者运行 ssh [email protected] 的用户，很可能会出现信息提示：

The authenticity of host 'github.com (xxx.xxx.xxx.xxx)' can't be established.
xxxxxxx key fingerprint is sHA256:xxx.
This key is not known by any other names.
Are you sure you want continue connecting(yes/no/[fingerprint])?

需要明确输入 yes 并回车，否则无法正确建立连接。

仓库文件结构

在克隆完成之后，可以使用 VSCode 等编辑器打开文件夹并进行编辑，其中首先需要了解的是文件的结构：

Directory.github
- Directoryworkflows
  - deploy.yml
Directorynode_modules/
- …
Directorypublic/
- …
Directorysrc
- Directoryassets/
  - …
- Directorycomponents/
  - …
- Directorycontent
  - Directorydocs
    Directoryimages/
    …
    Directoryfolders
    index.md
.gitignore
astro.config.mjs
package.json
pnpm-lock.yaml
README.md
tsconfig.json

其中例如 .gitignore, package.json, pnpm-lock.yaml, tsconfig.json 均为 Git 以及 Node.js 的相关配置文件，无需过于调整。其中 astro.config.mjs 为 astro 的配置文件，而其他的文件夹则按照文档的组织进行排序，其中本项目中全部的图片均维护在 src/content/docs/images 文件夹中。读者需要关注的除了 astro.config.mjs 之外，其余的只需要关注 src/content/docs 文件夹，并在其中组织你的 Markdown 文档。

安装 NodeJS

前往 NodeJS 官网下载预构建安装程序，之后运行并进行安装即可，在这里不进行赘述。

在安装之后进入 Shell 并查看 NodeJS 版本并安装 pnpm：

node -v
npm -v
npm install -g pnpm

对于 Ubuntu 则可以使用：

sudo apt install nodejs
sudo npm install n -g
sudo n 20.16.0
npm -v
node -v
# 如果为 20.16.0 则执行，否则重启终端或者尝试执行 hash -r
npm install -g pnpm

构建项目

在项目根目录下打开终端并运行：

pnpm i
pnpm dev

第一行进行依赖的安装，第二行进行项目的运行，此时可以在本地访问网页，具体 url 见终端输出。

撰写文档

在了解了文件结构之后便可以开始撰写文档了，确认自己想要撰写的文档所隶属于的类别，并进入该文件夹，新建一个 Markdown 文档，按照 Markdown 文档的语法进行撰写。

与此同时值得注意的是，Astro 支持部分的 Markdown 拓展语法，这些内容可以在官方文档中查阅。

Astro 配置

详细的 Astro 配置请参考 Astro 官方文档，这里只介绍 Astro 配置的必要内容。

当读者想要重新新建一个文档的时候，需要在 astro.config.mjs 文件中进行配置，以下是一个示例：

export default defineConfig({
  integrations: [
    starlight({
      ...,
      sidebar: [
        {
          label: '关于我们',
          slug: '关于我们',
        },
        {
          label: '贡献指南',
          slug: '贡献指南',
        },
        {
          label: 'Guides',
          items: [
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

在 integrations 中找到 starlight 集成，并找到 sidebar 侧边栏。
假如说想要添加一则新文档 关于我们.mdx，使用 label 添加到侧边栏标题，并在 slug 中填写路径即可，可以省略后缀名。
假如说在某一目录下添加一则新文档 guides/example.mdx，且在侧边栏中显示在 Guides 下面，则需要使用 items 字段，并在其中添加一个新的对象，规则不变。
对于目录 reference，可以注意到其中包含了 autogenerate 字段，该字段可以自动生成目录，从而不需要手动添加。

提交更改

在完成了文档的修改之后，可以使用 Git 进行更改的提交：

git pull origin main
git add .
git commit -m "your commit message"
git push origin main

之后可以看到自己的更改已经提交到了自己的 Github 仓库中。

发起 Pull Request

假如说进行了成功的提交，可以注意到，自己的仓库中应显示如 1 commit ahead of 的字样。点击 Contribute 并点击 Open pull request 即可发起一个 Pull Request，并等待管理员进行审核。

alt text

请确保 PR 的 title 中表意明确，同时 description 中清晰描述了自己添加的内容，之后点击 Create pull request 即可，管理员在收到内容之后会进行审查并给出 comment 或直接将你的 PR Merge 进主分支，即完成了贡献。

alt text

完成贡献

进行了上述的内容，便成功完成了一次贡献，你的内容将保留在 CABAOYAN2025 中，并为后来者指引方向。

保研经验贴贡献流程

贡献者可以在 /src/content/docs/保研经验贴/2024年 中新开一则 Markdown 文档，并按照 Markdown 的语法进行撰写，并使用上述流程进行投稿；或者已经在其他平台进行了投稿的，可以在 /docs/保研经验贴/2024年/index.md 文档中添加自己的链接。

对于新开 Markdown 文档，需要按照以下格式：

标题：标题自拟，但需要与文档内容相关，尽量包含个人昵称等，以免命名冲突。至少需要包含一个一级标题，为文档标题，其余标题至多为二级标题。
文件命名：文件名需要与标题一致，例如 阿汐2024年保研记录.md。
图片等：一般来说建议使用图床等方式插入图片，笔者曾有使用 Github 搭建图床的记录，供参考。

对于添加链接的方式，需要按照格式：* @[你的昵称](你的主页或者社交平台链接)的[文章标题](文章链接) 进行添加，这类内容在 /docs/保研经验贴 的往届内容中均有示例，请参考。

致全体贡献者

感谢每一位贡献者的辛勤贡献，你们均无私地将信息进行了开源分享，这有助于未来的每一位保研er更好地求学，并前往更好的地方，更好的提升自我，向你们每一位致以最诚挚的感谢。