From 66285a56cf8d7fc9ed5932dc37d78f29e4dfa46d Mon Sep 17 00:00:00 2001 From: YuYang Shen Date: Mon, 1 Sep 2025 17:53:19 +0800 Subject: [PATCH] Add Readme Getting Started Markdown --- README.md | 32 ++- Readme/git.md | 214 ++++++++++-------- .../Readme => Readme/img}/vscode_checkout.png | Bin .../Readme => Readme/img}/vscode_git.png | Bin .../img}/vscode_new_branch.png | Bin .../Readme => Readme/img}/vscode_push.png | Bin Readme/markdown.md | 184 +++++++++++++++ 7 files changed, 331 insertions(+), 99 deletions(-) rename {source/_images/Readme => Readme/img}/vscode_checkout.png (100%) rename {source/_images/Readme => Readme/img}/vscode_git.png (100%) rename {source/_images/Readme => Readme/img}/vscode_new_branch.png (100%) rename {source/_images/Readme => Readme/img}/vscode_push.png (100%) create mode 100644 Readme/markdown.md diff --git a/README.md b/README.md index db0f716..592057b 100644 --- a/README.md +++ b/README.md @@ -29,20 +29,38 @@ Manlink Knowledge Base ### VSCode-Git 使用说明 1. 在完成环境部署后，vscode中源代码管理功能应可用，从侧边栏中访问该功能 - ![VSCode Git](./source/_images/Readme/vscode_git.png) + ![VSCode Git](./Readme/img/vscode_git.png) 2. 想要对知识库页面进行编辑时，需**签出新分支**，参考下图步骤 - ![](./source/_images/Readme/vscode_checkout.png) - ![](./source/_images/Readme/vscode_new_branch.png) + ![](./Readme/img/vscode_checkout.png) + ![](./Readme/img/vscode_new_branch.png) -> **Warning** +> [!CAUTION] > 请不要直接对`master`分支进行修改！ >修改前请**签出**分支，修改完成后请发起***合并分支***请求 3. 在进行编辑后点击这里进行推送/发布新分支 - ![](./source/_images/Readme/vscode_push.png) + ![](./Readme/img/vscode_push.png) -> **Info** +> [!NOTE] +> > 想要更加详细了解Git可以参考[这篇文档](./Readme/git.md) -### 合并修改 +### 添加/修改内容 + +1. 本知识库采用`Sphinx`作为解析、生成工具，并*推荐*主要以`Markdown`语言作为文档的原始语言格式,`reStructuredText`语言作为辅助 +2. `source`文件夹即为知识库原始文件夹，通过文件树及`index.rst`进行网页层级管理 + +> [!IMPORTANT] +> 请**不要**修改`source/conf.py`其为`Sphinx`配置文件！如需修改请提交PR至管理员 + +3. 创建文档时： + 1. 请将图片放入`_images/`目录下，建议单独创建文件夹以保证目录整洁 + 2. 其他数据，如：实验数据、日志等，请放入`_static/`目录下，同样建议创建文件夹以保证目录整洁 + 3. 对于新创建的文档： + 1. 如已存在对应目录，则仅需在对应目录下创建文档即可，建议保证文件名具有**通俗易懂**的可读性 + 2. 如不存在目录，则需创建目录及`index.rst`，并更新上级的`index.rst`或`index.md`，具体内容可参考已有文档，如[子目录index.rst](./source/Mars_1KS/DC/PPMU/1.0/index.rst)及[父目录index.rst](./source/Mars_1KS/index.rst)之后新建文档 + +> [!Note] +> +> 对于Markdown语法，可以参考[这篇文档](./Readme/markdown.md) \ No newline at end of file diff --git a/Readme/git.md b/Readme/git.md index 2cc68d2..f018415 100644 --- a/Readme/git.md +++ b/Readme/git.md @@ -1,141 +1,171 @@ - -好的，没问题。这是一份为您和您的同事量身定制的 Git 和 Gitea 使用说明文档，专注于日常开发流程，并融入了 VSCode 的操作提示。 - ---- - # Git 与 Gitea 协作开发指南 -本文档面向已经完成环境搭建的同事，旨在帮助大家快速上手使用 Git 和公司内网的 Gitea 服务平台进行日常代码协作。我们将使用 VSCode 作为主要开发工具。 +## 文档说明 -## 1. 核心概念速览 +本文档面向公司内部已配置好开发环境（VSCode、Git、Gitea）的同事，旨在规范并指导如何使用 Git 和公司内网的 Gitea 服务平台进行高效的日常代码协作。本文档不包含环境安装与部署内容。 -理解以下几个概念，后续操作会更容易： +## 1. 术语表 (Glossary) -* **仓库 (Repository)**：一个项目所有的文件和历史记录，就是一个仓库。分为： - * **远程仓库 (Remote)**：存放在 Gitea 服务器上的仓库，是大家共享和协作的中心。 - * **本地仓库 (Local)**：存放在你自己电脑上的仓库，是你个人工作的地方。 -* **克隆 (Clone)**：将远程仓库**完整地下载**到你的本地电脑，这是开始参与一个已有项目的第一步。 -* **提交 (Commit)**：将你对代码的修改**打包并保存**到本地仓库的历史记录中。每次提交都需要附上一个简短的说明，描述这次修改的内容。 -* **推送 (Push)**：将你在本地仓库的提交**上传**到远程仓库（Gitea），让其他同事能看到你的工作成果。 -* **拉取 (Pull)**：将远程仓库（Gitea）上其他人的最新提交**下载并合并**到你的本地仓库，让你的本地代码保持最新。 -* **分支 (Branch)**：一条独立的工作线。通常，`main` (或 `master`) 分支是稳定可用的主分支。开发新功能或修复 Bug 时，我们会在新的分支上进行，完成后再合并回主分支，这样可以避免影响主分支的稳定性。 +| 术语/缩写 | 全称/解释 | 说明 | +| :--- | :--- | :--- | +| **Repository (Repo)** | 仓库 | 一个项目所有的文件和历史记录。可以理解为你的项目文件夹及其所有变更记忆。 | +| **Local** | 本地 | 指存储在你个人电脑上的仓库。 | +| **Remote** | 远程 | 指存储在服务器（如 Gitea）上的仓库，是团队协作的中心。 | +| **Clone** | 克隆 | 将**远程仓库**完整下载到本地的操作。这是获取项目代码的起点。 | +| **Commit** | 提交 | 将你的代码变更**打包并保存**到本地仓库历史记录中的操作。每次提交都需要一条说明信息。 | +| **Push** | 推送 | 将你本地仓库的提交**上传**到远程仓库的操作，使你的工作成果对他人可见。 | +| **Pull** | 拉取 | 将远程仓库的最新提交**下载并合并**到本地的操作，用于同步他人的工作成果。 | +| **Fetch** | 获取 | 从远程仓库**下载**最新的变更信息到本地，但**不会自动合并**到你的工作文件中。让你可以查看他人进度，再决定是否拉取。 | +| **Branch** | 分支 | 一条独立的开发线。主分支（如 `main`）应保持稳定，新功能应在**特性分支**上开发。 | +| **Merge** | 合并 | 将一个分支的修改整合到另一个分支的操作（例如，将功能分支合并到主分支）。 | +| **Pull Request (PR)** | 拉取请求 | **一个核心协作流程**。它是 Gitea 等平台的功能，用于发起代码合并请求，并进行代码评审（Code Review）、讨论和自动化检查。 | +| **Issue** | 议题/问题 | 用于**跟踪任务、功能请求和 Bug**。每个 Issue 应有清晰的标题和描述，可以被分配、分类和讨论。 | +| **`.gitignore`** | - | 一个特殊的配置文件，用于告诉 Git 哪些文件或目录**不需要**纳入版本控制（如日志文件、编译产物、本地配置文件等）。 | +| **Conflict** | 冲突 | 当多个人修改了同一文件的同一区域时，Git 无法自动合并，需要**人工介入**解决的情况。 | +| **HEAD** | - | 通常指向你当前所在的分支的最新提交，可以理解为“你当前的工作目录状态”。 | --- -## 2. 日常工作流程 (核心) +## 2. 核心工作流程 -这是你最常用到的操作序列。 +### 2.1. 初始化：克隆仓库 (Clone) -### 场景：开始一天的工作 - 获取最新代码 +参与一个已有项目的第一步是获取代码。 -1. **打开项目**：在 VSCode 中打开你的项目文件夹。 -2. **拉取最新代码**： - * **方法一 (VSCode GUI)**：点击左侧活动栏的**源代码管理**图标（或按 `Ctrl+Shift+G`），在界面顶部点击 **...** 更多操作菜单，选择 **拉取 (Pull)**。 - * **方法二 (命令行)**：打开 VSCode 的集成终端 (Ctrl+`)，输入： - ```bash - git pull origin main - ``` - （请将 `main` 替换为你实际使用的分支名，如 `master`, `develop` 等） +1. 打开浏览器，访问项目的 Gitea 页面。 +2. 找到并点击 **克隆** 按钮，复制提供的 URL（通常以 `http://...` 开头）。 +3. 在 VSCode 中： + * 按 Ctrl+Shift+P 打开命令面板。 + * 输入 `Git: Clone` 并选择。 + * 粘贴刚才复制的 URL，按回车。 + * 选择本地存储项目的目录。 +4. 克隆完成后，VSCode 会提示你打开克隆的项目。 -> **最佳实践**：每天开始工作前和提交代码前，先执行 `git pull`，可以有效减少代码冲突。 +### 2.2. 每日循环：获取与同步 -### 场景：提交你的工作 - 保存并分享你的修改 +**每天开始工作前**，务必先同步远程的最新代码到本地，以避免冲突。 -当你完成一部分代码后，需要将其提交并推送到远程仓库。 +* **推荐操作：拉取 (Pull)** + * **VSCode GUI**: 点击左侧源代码管理图标 -> 点击顶部 **...** -> 选择 **拉取 (Pull)**。 + * **终端命令**: `git pull origin <当前分支名>` -1. **暂存更改 (Staging)**：在 VSCode 的“源代码管理”面板，可以看到所有更改的文件。点击文件旁的 **+** 号，或点击更改列表上方的 **+** 号，将文件放入“暂存区”。这表示你准备要提交这些文件。 +* **可选操作：获取 (Fetch) + 拉取** + * 如果你想先查看别人改了什么再决定是否合并，可以先 **获取**： + * **VSCode GUI**: ... -> **获取 (Fetch)** + * **终端命令**: `git fetch` + * 获取后，你可以在 VSCode 的左下角分支状态栏或源代码管理视图看到远程的更新提示，然后再决定拉取。 - +### 2.3. 开发流程：基于分支的策略 -2. **提交 (Commit)**：在上方的输入框内填写清晰的提交信息（例如：“修复了用户登录的逻辑错误”），然后按 Ctrl+Enter (Windows) 或 CMD+Enter (Mac) 提交。你也可以点击输入框旁的 ✓ 图标进行提交。 +我们采用 **功能分支工作流**。严禁直接在 `main` 或 `develop` 等主分支上直接开发新功能。 - +1. **创建新分支**： + * 确保你当前在**主分支**上（例如 `main`），并且已经执行了 **拉取** 操作。 + * 点击 VSCode 窗口左下角的分支名 -> 选择 **创建新分支...** -> 输入分支名 -> 回车。 + * **分支命名规范**： + * 功能：`feat/简短描述`，例如 `feat/user-auth` + * Bug修复：`fix/问题描述`，例如 `fix/login-crash` + * 文档：`docs/更新内容`，例如 `docs/api-update` + * 热修复：`hotfix/紧急问题`，例如 `hotfix/prod-issue` -3. **推送 (Push)**：提交只是保存在了本地。需要点击 **源代码管理** 面板顶部的 **...** 菜单，选择 **推送 (Push)**，才能将本次提交上传到 Gitea。 +2. **在新分支上开发**：在此分支上完成你的编码、测试等工作。 - * **命令行等效操作**： - ```bash - git add . # 暂存所有更改 - git commit -m "你的提交信息" # 提交到本地仓库 - git push origin your-branch-name # 推送到远程分支 - ``` +3. **提交更改**： + * 在 VSCode 的“源代码管理”面板，看到所有更改的文件。 + * 点击文件旁的 **+** 号或将文件拖到“暂存更改”区域。 + * 在上方输入框撰写**清晰的提交信息**。 + * **格式建议**：`[类型] 简短描述`，例如 `[Feat] 增加微信登录功能` 或 `[Fix] 修复首页图片无法加载的问题`。 + * 按 Ctrl+Enter (Mac: CMD+Enter) 提交到**本地仓库**。 ---- +4. **推送分支**： + * 首次推送新分支时，VSCode 会提示你发布（推送）分支。点击提示或点击源代码管理顶部的 **...** -> **推送**。 + * 这将把你的本地分支和所有提交推送到 Gitea，并在远程创建同名分支。 -## 3. 分支管理策略 +### 2.4. 协作流程：发起拉取请求 (Pull Request) -我们通常采用 **功能分支工作流**。 +完成功能开发后，需要将代码合并回主分支。 -### 创建新功能分支 - -不要在 `main` 分支上直接开发！为新功能或 Bug 修复创建一个独立分支。 - -1. **查看当前分支**：VSCode 窗口的左下角会显示当前分支名（例如：`main`）。 -2. **创建新分支**：点击左下角的分支名，在弹出的顶栏中选择 **创建新分支...**，输入分支名（例如：`feat/user-profile-avatar`），然后按回车。VSCode 会自动切换到新分支。 - - - - * **分支命名建议**： - * 功能：`feat/简短描述` - * Bug修复：`fix/问题描述` - * 文档：`docs/更新内容` - -### 合并分支与 Pull Request (PR) - -当你完成开发并测试通过后，需要将分支合并回 `main` 分支。我们通过 Gitea 的 **Pull Request (PR)** 功能来完成，这是代码评审的关键环节。 - -1. **推送你的分支**：确保你已经将本地分支推送到了 Gitea (`git push origin your-branch-name`)。 +1. **推送最终代码**：确保你已将分支的所有提交都推送到 Gitea。 2. **在 Gitea 上创建 PR**： - * 浏览器打开你的项目 Gitea 页面（例如：`http://your-gitea-company.com/your-group/your-project`）。 - * 通常会看到一条提示，显示你刚刚推送的分支，点击 **创建拉取请求** 按钮。 - * 或者，切换到 **Pull Requests** 标签页，点击 **New Pull Request**。 + * 浏览器打开你的项目 Gitea 页面。 + * 通常页面上会有你刚推送分支的提示，直接点击 **创建拉取请求** 按钮。 + * 或手动切换到 **Pull Requests** 标签页 -> **New Pull Request**。 3. **填写 PR 信息**： - * **标题**：清晰概括本次 PR 的内容。 - * **描述**：详细说明修改内容、原因（可选）测试情况等。可以贴上相关任务的链接。 - * 选择正确的**基础分支** (通常是 `main`) 和**对比分支** (你的功能分支)。 -4. **申请评审**：可以指定一位或多位同事对你的代码进行评审（Review）。 -5. **合并 PR**：通过评审后，你或具有权限的同事可以在 Gitea Web 界面上操作合并（Merge）。合并后，你的功能就正式成为了主代码的一部分。 + * **标题**：清晰概括 PR 内容，建议使用提交信息的格式。 + * **描述**： + * 详细说明修改内容、动机、测试方法。 + * **关键：关联 Issue**。在描述中输入 `#` 后会提示相关的 Issue，选择即可。使用 `Closes #15`, `Fixes #32` 等关键词，合并后可自动关闭对应 Issue。 + * 如有界面变动，最好附上截图或屏幕录制。 + * 选择正确的**基础分支** (如 `main`) 和**头部分支** (你的功能分支)。 +4. **发起评审**：可以指定相关同事进行评审（Review）。 +5. **处理评审意见**：评审者可能会在 PR 中提出评论。请根据意见在本地修改代码，然后再次**提交并推送**，新的提交会自动追加到该 PR 中。 +6. **合并与清理**： + * 通过评审后，由有权限的成员在 Gitea 上操作合并。 + * 合并后，可以在 Gitea 上**删除已合并的功能分支**（通常有选项）。 + * **本地清理**：切换回 `main` 分支 -> 拉取最新代码 -> 删除本地已合并的功能分支 (`git branch -d feat/your-branch`)。 --- -## 4. 常见问题与解决 +## 3. 常见问题与解决方案 -### 1. 推送失败：提示“非快进式更新” +### 3.1. 推送失败：非快进式更新 -**原因**：在你推送之前，远程分支已经有了新的提交，导致你的本地历史落后于远程历史。 +**现象**：`git push` 时提示 `! [rejected] error: failed to push some refs...` + +**原因**：在你推送之前，远程分支已经被别人更新了。 **解决**： -1. 先执行 `git pull origin your-branch-name` 拉取远程的最新代码。 -2. Git 会自动尝试合并。如果合并顺利，解决可能出现的冲突后，再次执行 `git push`。 +1. 执行 `git pull origin <你的分支名>` 拉取远程的最新代码并合并到本地。 +2. 解决可能出现的**合并冲突**（见下节）。 +3. 再次执行 `git push`。 -### 2. 拉取时出现“合并冲突” +### 3.2. 合并冲突 (Conflict) -**原因**：你修改的代码和别人修改的代码在同一位置，Git 无法自动判断该保留谁的。 +**现象**：执行 `git pull` 或合并分支时，提示 `CONFLICT (content)`。 **解决**： -1. **不要慌张**，这是协作中的正常现象。 -2. 在 VSCode 中，冲突文件会被特殊标记。打开冲突文件，你会看到类似这样的内容： +1. **保持冷静**，冲突是协作的正常部分。 +2. 在 VSCode 中，冲突文件会被突出显示。打开文件，你会看到 Git 的冲突标记： ```python <<<<<<< HEAD - 这是你本地修改的内容 + 这是你本地修改的代码 ======= - 这是远程分支上别人的修改 - >>>>>>> a1b2c3d4... + 这是远程分支上的代码 + >>>>>>> commit-hash... ``` -3. **手动解决**：与冲突代码的作者沟通，决定保留哪一部分，或者进行整合。删除 `<<<<<<<`, `=======`, `>>>>>>>` 这些标记。 -4. **标记为已解决**：在 VSCode 的“源代码管理”面板，解决完所有冲突后，点击该文件右边的 **...**，选择 **标记为已解决**。 -5. **完成合并**：像往常一样，执行提交（这次提交信息通常是合并自动生成的）和推送。 +3. **沟通与决策**：与冲突代码的作者（可通过 Git 历史或团队沟通工具联系）讨论，决定保留哪一部分代码，或进行整合。 +4. **手动解决**： + * 删除不需要的代码块。 + * **必须删除**所有冲突标记 (`<<<<<<<`, `=======`, `>>>>>>>`)。 +5. **标记为已解决**： + * 在 VSCode 的“源代码管理”面板，解决后的文件会出现在“已暂存的更改”中。 + * 右键点击该文件 -> **选择阶段更改**（如果未自动暂存）。 +6. **完成合并**： + * 像正常提交一样，输入一个合并提交信息（如 `Merge branch 'main' into feat/xxx`）。 + * 提交并推送。 --- -## 5. VSCode 小贴士 +## 4. VSCode 高效技巧 -* **图形化界面**：多使用“源代码管理”视图的按钮和右键菜单，大部分操作都可以点击完成，无需记忆命令。 -* **差异对比**：在“源代码管理”面板点击更改的文件，可以直观地看到具体修改了哪些代码（绿色是新增，红色是删除）。 -* **集成终端**：VSCode 内置了终端 (Ctrl+`)，可以直接在其中输入 Git 命令，无需切换窗口。 +1. **图形化界面**：多使用“源代码管理”视图和右键菜单，大部分操作无需命令。 +2. **差异对比**：点击更改的文件，可直观查看代码行级别的变化（绿色新增，红色删除）。 +3. **行内暂存**：在更改文件的代码行号旁边，点击 **+** 号可以只暂存该行的修改，而不是整个文件，用于提交精炼的更改。 +4. **集成终端**：使用 VSCode 内置终端 (Ctrl+`) 执行 Git 命令，工作流无缝衔接。 +5. **时间线视图**：点击单个文件，在编辑区下方可以看到该文件的**时间线**，展示所有的历史提交记录，方便追溯变更。 + +## 5. 最佳实践总结 + +1. **勤提交**：小步快跑，频繁提交。每次提交只做一个明确的修改，并写好清晰的提交信息。 +2. **勤拉取**：开始工作前、提交代码前，先 `pull` 一下，与主线保持同步。 +3. **开分支**：任何新功能或 Bug 修复，都从新建分支开始。 +4. **早提 PR**：功能未完全完成但希望早期评审时，可以创建 **Draft PR**（Gitea 支持）。 +5. **看提示**：密切关注 VSCode 左下角分支状态栏的同步状态提示（如 `↑3` 代表有3个本地提交未推送，`↓2` 代表有2个远程提交未拉取）。 +6. **用 Issues**：开发前先创建 Issue 来规划和跟踪任务，并在 PR 中关联它们。 ## 获取帮助 -* 本地的命令帮助：在终端输入 `git help <命令>`，如 `git help push` +* **本地帮助**：在终端输入 `git help <命令>`，如 `git help commit`。 -希望这份指南能帮助你顺畅地开始协作开发！ \ No newline at end of file + +祝您编码愉快，协作顺利！ \ No newline at end of file diff --git a/source/_images/Readme/vscode_checkout.png b/Readme/img/vscode_checkout.png similarity index 100% rename from source/_images/Readme/vscode_checkout.png rename to Readme/img/vscode_checkout.png diff --git a/source/_images/Readme/vscode_git.png b/Readme/img/vscode_git.png similarity index 100% rename from source/_images/Readme/vscode_git.png rename to Readme/img/vscode_git.png diff --git a/source/_images/Readme/vscode_new_branch.png b/Readme/img/vscode_new_branch.png similarity index 100% rename from source/_images/Readme/vscode_new_branch.png rename to Readme/img/vscode_new_branch.png diff --git a/source/_images/Readme/vscode_push.png b/Readme/img/vscode_push.png similarity index 100% rename from source/_images/Readme/vscode_push.png rename to Readme/img/vscode_push.png diff --git a/Readme/markdown.md b/Readme/markdown.md new file mode 100644 index 0000000..8c242c7 --- /dev/null +++ b/Readme/markdown.md @@ -0,0 +1,184 @@ + +好的，没问题。这是一份为您和您的同事准备的 Markdown 使用指南，风格和受众与之前的 Git 文档保持一致。 + +--- + +# Markdown 协作书写指南 + +## 文档说明 + +本文档面向公司内部所有需要使用 Markdown 语言书写文档的同事。Markdown 是一种轻量级标记语言，允许人们使用易读易写的纯文本格式编写文档，并可转换为有效的 HTML 文档。我们将在 **VSCode** 中编写，并托管在 **Gitea** 上进行版本管理与协作。 + +## 1. 术语表 (Glossary) + +| 术语 | 解释 | +| :--- | :--- | +| **Markdown (.md)** | 一种轻量级标记语言，使用纯文本格式的语法，使其易读、易写，并可转换为结构化的 XHTML/HTML。 | +| **语法 (Syntax)** | 一套规则体系，定义了如何通过简单的符号（如 `#`, `*`, `-` 等）来格式化文本。 | +| **渲染 (Rendering)** | 将 Markdown 源代码解析并转换为可视化的、格式优美的文档（如 HTML、PDF）的过程。 | +| **预览 (Preview)** | 在编写 Markdown 时实时查看其渲染后效果的功能。 | +| **GFM (GitHub Flavored Markdown)** | GitHub（及 Gitea）对标准 Markdown 的扩展，提供了表格、任务列表等实用功能。 | +| **扩展语法 (Extended Syntax)** | 并非所有 Markdown 处理器都支持的额外语法，如表格、脚注、定义列表等。 | + +--- + +## 2. 为什么使用 Markdown？ + +* **通用性强**：广泛用于 `README` 文件、论坛帖子、文档、博客、代码注释等。 +* **专注于内容**：无需关心字体、颜色等样式，只需用简单的符号定义结构。 +* **纯文本特性**：意味着： + * 兼容所有文本编辑器。 + * 非常适合用 **Git** 进行版本控制，差异对比清晰明了。 + * 永远不会因为软件换代而过时。 +* **可转换**：轻松转换为 HTML、PDF、Word 等多种格式。 + +--- + +## 3. 核心语法速查表 + +这是你最常用到的 90% 的语法。 + +### 3.1. 标题 (Headers) + +使用 `#` 的数量来表示标题的级别，从 1 级（最大）到 6 级（最小）。 + +```markdown +# 一级标题 (H1) +## 二级标题 (H2) +### 三级标题 (H3) +#### 四级标题 (H4) +##### 五级标题 (H5) +###### 六级标题 (H6) +``` + +### 3.2. 强调 (Emphasis) + +```markdown +*这是斜体文本* 或 _这也是斜体文本_ +**这是粗体文本** 或 __这也是粗体文本__ +***这是粗体加斜体*** 或 ___这也是粗体加斜体___ +``` + +### 3.3. 列表 (Lists) + +**有序列表 (Ordered Lists)：** 使用数字加点号 +```markdown +1. 第一项 +2. 第二项 +3. 第三项 +``` + +**无序列表 (Unordered Lists)：** 使用 `-`, `*`, 或 `+` +```markdown +- 列表项 +- 另一个列表项 + - 嵌套列表项（缩进两个空格或一个制表符） +``` + +**任务列表 (Task Lists - GFM 特性)：** 非常适合记录待办事项 +```markdown +- [x] 已完成的任务 +- [ ] 未完成的任务 +``` + +### 3.4. 链接与图片 (Links & Images) + +**链接：** +```markdown +[显示的链接文本](https://www.example.com "悬停提示文本（可选）") +``` + +**图片：** +```markdown +![图片的替代文本(alt text)](images/logo.png "悬停提示文本（可选）") +``` +> **最佳实践**：使用 `source\_images` 文件夹来存放图片, `source\_static`来存放静态数据，并使用**相对路径**引用，这样在 Gitea 上也能正确显示。 + +### 3.5. 代码 (Code) + +**行内代码 (Inline Code)：** 用反引号包裹 +```markdown +使用 `git commit` 命令来提交更改。 +``` + +**代码块 (Code Blocks)：** 用三个反引号包裹，并可选指定语言以实现语法高亮 +````markdown +```python +def hello_world(): + print("Hello, World!") +``` +```` + +### 3.6. 引用 (Blockquotes) + +使用 `>` 符号表示引用。 +```markdown +> 这是引用的文本。 +> 这是引用的文本。 +> +> > 这是嵌套的引用。 +``` + +### 3.7. 表格 (Tables - GFM 特性) + +使用连字符 `-` 来分隔表头，管道符 `|` 来分隔列。 +```markdown +| 左对齐 | 居中对齐 | 右对齐 | +| :----- | :------: | -----: | +| 单元格 | 单元格 | 单元格 | +| 单元格 | 单元格 | 单元格 | +``` + +--- + +## 4. VSCode 中的高效书写 + +VSCode 对 Markdown 提供了强大的原生支持。 + +1. **实时预览 (Preview)**： + * 打开一个 `.md` 文件。 + * 点击编辑器右上角的 **拆分编辑器** 图标，或按 `Ctrl+K V`（按住 `Ctrl+K`，松开再按 `V`）。 + * 右侧将打开一个实时渲染的预览窗口，与你左侧的编辑同步滚动。 + +2. **快捷键与自动补全**： + * **加粗**：选中文本，按 `Ctrl+B`。 + * **斜体**：选中文本，按 `Ctrl+I`。 + * **代码块**：输入三个反引号 ```` ``` ```` 后按回车，VSCode 会自动补全并让你输入语言类型。 + * **列表**：输入 `- ` 或 `1. ` 后，按回车会自动创建下一项。 + +3. **目录生成 (TOC)**： + * 有许多扩展可以自动根据标题生成目录（如 `Markdown All in One`）。 + * 在 Gitea 中，仓库的 `README.md` 文件会自动根据标题生成目录。 + +4. **代码格式化**： + * 安装 `Markdownlint` 等扩展，它可以帮你自动格式化 Markdown 文档并标记出不符合规范的写法。 + +--- + +## 5. 与 Gitea/Git 的协作 + +1. **版本控制**：`.md` 文件是纯文本文件，非常适合用 Git 管理。每次对文档的修改（修正错别字、增加章节）都可以清晰地通过 `git diff` 看到。 + +2. **Gitea 渲染**：Gitea 完全支持 GFM。你推送至 Gitea 的任何 `.md` 文件都会在网页上被自动渲染成美观的文档。 + +3. **使用 Issues 和 PR 协作修改文档**： + * 发现文档错误或想贡献内容？和代码一样： + 1. **Fork** 或 **Clone** 仓库。 + 2. 基于 `main` 分支创建一个新分支（如 `docs/fix-typo`）。 + 3. 修改 `.md` 文件。 + 4. 提交更改，写清提交信息（如 `[Docs] 修复用户手册中的拼写错误`）。 + 5. 推送分支并发起 **Pull Request (PR)**。 + * 其他同事可以在 PR 中对文档修改进行**评审（Review）**，提出建议。 + +--- + +## 6. 最佳实践与规范 + +1. **保持简洁**：Markdown 的哲学是易读易写。不要滥用复杂格式。 +2. **标题层级**：从 `H1` 开始，按顺序使用，不要跳级。 +3. **中英文混排**：中英文之间加一个空格，例如：“学习 Markdown 语言” 而不是 “学习Markdown语言”。 +4. **统一的图片管理**：在项目根目录建立 `assets` 或 `images` 文件夹，所有图片统一放入。 +5. **行尾不要留空格**：这可能会在某些渲染器中导致意外的换行。 +6. **善用代码块**：对于命令行操作、配置代码等，务必使用代码块，提高可读性。 + +现在，你可以开始使用 Markdown 高效、优雅地书写所有文档了！ \ No newline at end of file