Week 7：Markdown 语法整理与 GitHub 作业规范

一、实验背景与目的

本周实验聚焦于 Markdown 文档语法的系统整理与 GitHub 仓库规范管理实践。Markdown 是 GitHub README、技术文档、ROS 项目说明的核心格式，掌握其语法是后续高质量提交作业的基础。本周目标包括：

系统学习 Markdown 常用语法（标题、列表、代码块、图片、表格等）
规范整理已有周次作业的 README 文件
理解 GitHub 仓库的目录结构组织方式
掌握通过 GitHub Pages 将仓库转为可访问网页的方法

二、Markdown 核心语法整理

1. 标题层级

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

标题层级对应 HTML 的 <h1> 到 <h4>，GitHub README 中一级标题用于文档主题，二级标题划分主要章节，三级标题用于小节细分。

2. 文字格式

**加粗文字**
*斜体文字*
~~删除线~~
`行内代码`

效果：加粗、斜体、~~删除线~~、代码

3. 列表

# 无序列表
- 第一项
- 第二项
  - 嵌套子项

# 有序列表
1. 第一步
2. 第二步
3. 第三步

4. 代码块

```bash
  ros2 run turtlesim turtlesim_node
```

```python
  import cv2
  img = cv2.imread("cat.jpg")
  cv2.imshow("Image", img)
  cv2.waitKey(0)
```

代码块通过三个反引号包裹，语言标识符（bash、python、cpp 等）启用语法高亮，是技术文档的核心格式。

5. 插入图片

# 基础语法
![图片描述](图片路径)

# 仓库内相对路径（推荐）
![实验截图](screenshot.png)

# 带链接的图片
[![图片](图片路径)](跳转链接)

6. 超链接

[链接文字](https://example.com)
[跳转到其他文件](/shizhuoyuan-/week2/)

7. 表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A   | B   | C   |
| D   | E   | F   |

表格是整理实验数据、对比参数的高效格式。

8. 引用块

> 这是一段引用内容
> 可以跨越多行

9. 分割线与任务列表

---

- [x] 已完成的任务
- [ ] 未完成的任务

三、GitHub 仓库规范整理

1. 目录结构规范

README.md：实验报告（必须）
截图文件（.png / .jpg）：实验过程记录
代码文件（.py / .cpp）：实验代码（如有）
视频文件（.mp4）：操作演示（如有）

shizhuoyuan-/
├── README.md          # 仓库主页，汇总所有周次链接
├── week2/
│   ├── README.md
│   └── screenshot.png
├── week3/
│   └── ...
└── _config.yml        # GitHub Pages 配置

2. README 编写规范

高质量的 README 应包含以下要素：

实验背景与目的：说明实验解决什么问题
实验环境：操作系统、工具版本、依赖库
实验步骤：可复现的操作流程（含命令）
实验现象：客观记录观察到的结果
问题分析：遇到的问题及解决方案
实验结论：总结核心收获
实验心得：个人学习体会与拓展思考

3. Git 提交规范

# 规范的提交信息格式
git commit -m "week7: 添加 Markdown 语法整理和 GitHub 规范文档"

# 常用命令
git add .               # 暂存所有修改
git commit -m "提交信息"  # 创建提交
git push origin main    # 推送到远程仓库
git log --oneline       # 查看提交历史
git diff                # 查看未暂存的修改

四、GitHub Pages 配置

本仓库已启用 GitHub Pages，在线访问地址：

🌐 https://shizhuoyuan39-droid.github.io/shizhuoyuan-

配置方法：

进入仓库 → Settings → Pages
Source 选择 main 分支，根目录
保存后等待约 1 分钟自动部署
在 _config.yml 中配置主题使页面更美观

# _config.yml
theme: jekyll-theme-cayman

五、Markdown 与其他文档格式对比

特性	Markdown	Word (.docx)	HTML
学习成本	低	低	中
版本控制友好	✅	❌	✅
GitHub 原生渲染	✅	❌	✅
排版灵活度	中	高	高
适合场景	技术文档、README	正式报告	网页

Markdown 在开源项目和技术社区中占主导地位，原因在于它与 Git 版本控制天然兼容——纯文本格式使得 diff 对比修改一目了然，而 Word 的二进制格式则无法做到这一点。

六、实验心得

文档即代码： Markdown 文档的规范程度直接反映了开发者的工程素养。在 ROS2 项目中，一份清晰的 README 能让团队成员快速理解项目结构和运行方式，节省大量沟通成本。养成每周整理 README 的习惯，本身就是一种有效的知识沉淀方式。

版本控制的习惯养成： 通过本周的仓库整理，我意识到每次提交都应该有意义——提交信息要清晰描述”做了什么”，而不是简单写”update”。良好的 Git 提交习惯是协作开发的基础，也是回顾学习历程的重要记录。

GitHub Pages 的价值： 将仓库部署为可访问的网页，不仅提升了展示效果，也是对个人学习成果的一种公开记录。对于未来求职或展示项目经历，一个维护良好的 GitHub 主页具有很强的说服力。