计算机协会文档

主题

撰写并发布你的第一篇 NBTCA 博客 ​

本指南带你用最主流的开源协作方式——Git + Markdown + Pull Request——撰写并发布你的第一篇 NBTCA 博客。若只想了解通用的 Git 协作流程，见快速上手 GitHub 工作流；本文在其基础上，讲博客投稿特有的部分。

目标是：

让每位新社员都能独立完成一篇博客投稿流程。

流程 ​

准备工作 ​

1. 安装 Git ​

Windows ​

前往 https://git-scm.com/downloads 下载并安装，保持默认选项即可。

macOS ​

先安装命令行工具集，再用 Homebrew 安装 Git：

bash
xcode-select --install
brew install git

Linux（例如 Ubuntu / Arch） ​

使用对应发行版的包管理器安装 Git：

bash
sudo apt install git
# 或
sudo pacman -S git

2. 注册 GitHub 账号 ​

访问 https://github.com，注册并登录，设置一个好记的用户名。

3. 基础配置 ​

bash
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

你也可以用 GitHub CLI 完成 GitHub 的认证过程，但 Git 的工作流程仍是必要掌握的基础。

Fork 与 Clone：向博客仓库贡献 ​

一般的工作流程是把源代码仓库 Fork 一份到自己名下，得到一个下游仓库；在下游仓库里编写内容，再通过创建 PR 把更新提交回上游仓库。

博客所在的 Home 项目集成了 CI/CD：PR 合并进 main 后，GitHub Actions 自动构建并上线，不论 PR 来自源仓库的分支还是 Fork。PR 本身不会触发构建，所以提交前请在本地跑一遍 pnpm build。有 Home 仓库写权限的成员可以直接在源仓库建分支，其他同学 Fork 后提交 PR 即可。

Clone ​

bash
git clone https://github.com/nbtca/home.git
cd home
# 如果是 gh-cli 则是 gh repo clone nbtca/home

创建分支 ​

bash
git checkout -b add-my-first-blog
# -b 参数代表创建一个新的分支
# 分支名 add-my-first-blog 可自行替换，
# 常见习惯是“类型/具体事务”，例如 post/blog-post、feature/homepage

撰写博客（Markdown 格式） ​

1. 新建文件 ​

在 src/pages/posts/ 文件夹中新建：

bash
my-first-blog.md
# 换成你喜欢的名字，最好是英文的方便管理

2. 文件模板 ​

markdown
---
layout: "../../layouts/MarkdownPost.astro"
title: "题目"
pubDate: 2025-10-10
description: "描述"
author: "张三"
cover:
  url: "封面地址url，也可以引用本地图片"
  alt: "cover"
tags: ["标签", "可多个"]
---

# Git 与 Markdown 入门指南

大家好，我是计算机协会新社员张三。

本文将介绍如何使用 Git 与 Markdown 撰写并提交博客。

## 一、Git 是什么？

Git 是一个分布式版本控制系统，用于多人协作开发。

## 二、Markdown 是什么？

Markdown 是一种轻量级标记语言，用简单的符号来排版文字。

- **加粗**：`**加粗**`
- _斜体_：`*斜体*`
- 链接：`[协会官网](https://example.com)`

## 三、总结

学会使用 Git + Markdown，你就能参与到开源协作中了！

以上为行文推荐格式，Markdown 的具体写法可自行查阅手册。

提交与推送 ​

bash
git add my-first-blog.md
# 将更新的文件添加到暂存区

git commit -m "Add my first blog: Git 与 Markdown 入门"
# 将暂存区的文件集合为一次提交，并对本次提交做出说明

git push origin add-my-first-blog
# 将提交从本地同步到远程 GitHub 仓库的对应新分支

创建 Pull Request（PR） ​

  1. 打开你的 GitHub 仓库。
  2. 点击 “Compare & pull request”。
  3. 填写标题与说明（例如 “新增一篇关于 Git 的博客”）。
  4. 目标仓库选择 nbtca/home。
  5. 提交 Pull Request。

常见问题 ​

问题解决方案
push 时提示拒绝访问检查是否使用 HTTPS 地址，并确认你已登录 GitHub。
提交重复文件或出错使用 git status 查看状态，git reset 撤销错误提交。
PR 没被合并可能格式不规范，等待管理员审核反馈。

推荐工具 ​

结语 ​

当仓库管理员完成 Review 后，你的提交就可以 Merge 进主仓库了。

当你第一次成功合并 PR 时：

恭喜你，🎉 你正式成为了开源协作的一员！