课程导读与协作规范

学习目标

了解本教程的整体结构与设计思路。
掌握仓库目录组织方式与各章节定位。
明确协作约定：分支策略、提交信息格式、PR 流程。

课程概述

本教程的目标是帮助一个团队（或学习者个人）从零搭建起一套基于 Obsidian + VS Code + Git 的协作写作环境，并系统掌握：

模块	涵盖内容
环境搭建	Obsidian、VS Code、Git 安装与配置
Markdown 写作	基础语法、扩展语法、Obsidian 特色语法
版本协作	Git 可视化操作、分支管理、冲突处理
知识组织	Canvas 画布、Bases 数据库
多端同步	Syncthing 局域网同步
AI 辅助	Copilot 基础、prompt、skill、mcp 实战

仓库结构

.
├── section0/          # 课程导读与协作规范 ← 你在这里
├── section1/          # 环境安装（已完 ✅）
├── section2/          # Markdown 基础语法
├── section3/          # Markdown 扩展与 Obsidian 语法
├── section4/          # Git/GitHub 可视化协作
├── section5/          # Obsidian Canvas
├── section6/          # Obsidian Bases
├── section7/          # Syncthing 局域网同步
├── section8/          # VS Code Copilot 基础
├── section9/          # Copilot 实战案例
├── appendix/          # 术语表 / FAQ / 更新日志
├── template/          # Markdown 模板
├── image/             # 图片资源
└── .doc/              # 内部规划文档

章节编号原则：先环境，后内容。建议按数字顺序学习，但也可根据需求跳转。

协作约定

1. 分支策略

main 分支：稳定版本，始终可发布。
功能分支：从 main 创建，命名格式为 feat/<描述> 或 docs/<section>。
- 示例：docs/section2-markdown-basic、fix/typo-readme

2. 提交信息格式

<type>(<scope>): <简短描述>

<可选正文>

推荐类型：

类型	用途
`docs`	文档相关
`feat`	新功能/新章节
`fix`	修复错误
`style`	格式/样式调整
`refine`	优化已有内容

示例：

docs(section2): 新增 Markdown 基础语法教程

- 标题、段落、列表、链接、图片、代码、引用
- 含练习题与验收清单

3. PR 流程

从 main 创建功能分支。
按编写规范撰写或修改文档。
推送分支到远程，创建 Pull Request。
指定 reviewer 审核，通过后合并到 main。

详细的 PR 操作步骤请参考 section4 教程。

4. 编写规范

所有教程文档遵循以下约定：

UTF-8 编码的 Markdown，首部使用统一 Frontmatter（title、tags、status、updated）。
每节包含固定段落：学习目标 → 前置条件 → 步骤 → 常见问题 → 练习任务 → 验收清单。
图片统一放在 image/ 或章节内 assets/ 子目录，使用相对路径引用。
示例命令优先提供 VS Code 可视化路径；命令行作为补充。
需要平台差异时明确标注 Windows / macOS / Linux。

5. 练习提交方式

每个章节末尾的”练习任务”是巩固学习成果的重要环节：

独立练习者：在本地按练习要求操作，自检验收清单。
团队学习者：可将练习成果（如一篇 Markdown 笔记、一个 Canvas 文件）提交到对应章节的 exercises/ 子目录，通过 PR 分享供审阅。

常见问题

Q：我是初学者，应该按什么顺序学习？
A：建议按 section0 → section1 → section2 → section3 → … 的顺序。如果时间紧张，至少先完成 section1（环境安装），确保工具可用。

Q：我主要是来学 Copilot 的，能跳过前面的章节吗？
A：可以跳至 section8，但建议至少完成 section1 的环境安装，并具备基础的 Markdown 知识。

Q：如何报告文档错误或提出改进建议？
A：请提交 Issue 或直接发起 PR，我们会尽快处理。

练习任务

阅读本文件，理解仓库结构和协作规范。
在本地创建一个新分支，命名如 docs/section0-fix，尝试修改本文件并提交。
推送到远程仓库，体验一次完整的 PR 流程（可选）。

验收清单

理解仓库目录结构与各章节内容定位
熟悉分支命名与提交信息格式
理解 PR 协作流程
了解编写规范和练习提交方式

Obsidian 教程

探索

00_课程导读与协作规范