Add Readme Getting Started Markdown

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 高效、优雅地书写所有文档了！