diff --git a/docs/en/contribute/documentation_writing_specifications.md b/docs/en/contribute/documentation_writing_specifications.md index 0793364707306d024d784d2f2d3addc134251dd2..97a203f1e477f139a2be7c5fb0d14ca35211d3c5 100644 --- a/docs/en/contribute/documentation_writing_specifications.md +++ b/docs/en/contribute/documentation_writing_specifications.md @@ -131,7 +131,7 @@ installation_and_deployment.md # Document for "Installation and Deployment" ![alt text](./path/to/image.png "optional title") ``` -**Rule**: Place all images in the **figures** subdirectory of the document folder. For example, the [A-Tune User Guide](https://docs.openeuler.org/en/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html) stores its images in [this directory](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/en/docs/A-Tune/figures). Always use **relative paths** for references. +**Rule**: Place all images in the **figures** subdirectory of the document folder. For example, the [A-Tune User Guide](https://docs.openeuler.org/en/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html) stores its images in [this directory](https://gitee.com/openeuler/docs-centralized/tree/stable2-22.03_LTS_SP2/docs/en/docs/A-Tune/figures). Always use **relative paths** for references. **Rule**: Only use original or properly licensed images to avoid copyright issues. diff --git a/docs/zh/contribute/_toc.yaml b/docs/zh/contribute/_toc.yaml index 3ba7396a1c45cbe5a61db31f39f82211cf39dada..d427d3416b3b98f4be1190fc9837d9e528212566 100644 --- a/docs/zh/contribute/_toc.yaml +++ b/docs/zh/contribute/_toc.yaml @@ -12,4 +12,10 @@ sections: - label: 文档发布流水线门禁 href: ./ci_rules.md - label: 文档开发工具 - href: ./doc_tools.md + sections: + - label: 介绍 + href: ./doc_tools_introduction.md + - label: 静态检查 + href: ./doc_tools_static_check.md + - label: 高级功能 + href: ./doc_tools_functions.md diff --git a/docs/zh/contribute/contribution_process.md b/docs/zh/contribute/contribution_process.md index 08bc70d2c5435d61fb8a28dadfc7721db8ed67da..2e3c7c61b39bd2ba7a3aff4382c274fee922acfa 100644 --- a/docs/zh/contribute/contribution_process.md +++ b/docs/zh/contribute/contribution_process.md @@ -2,17 +2,17 @@ ## 概述 -openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理，托管于 Gitee 平台，文档修改通过 Pull Request（PR）工作流进行审核与合并。openEuler 文档分仓存储，《发行说明》、《安装指南》、《升级指南》等基础特性文档存在 openEuler/docs 仓，由 DOC SIG 维护。《A-Tune 用户指南》等增量特性文档分别存在各特性代码仓，由各特性 SIG 组维护。 +openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本控制，并托管在 Gitee 平台。文档修改通过 Pull Request（PR）工作流进行审核与合并。openEuler 文档分仓存储，《发行说明》、《安装指南》、《升级指南》等基础特性文档存放在 openEuler/docs 仓，由 DOC SIG 负责维护。《A-Tune 用户指南》等增量特性文档存放在各特性代码仓，由对应 SIG 组维护。 文档中心将手册[按业务场景和工具模块分类](./directory_structure_introductory.md#文档存放地址)，常见的文档开发场景如下： - 新增场景：需联系 DOC SIG maintainer 修改。 -- 新增手册：新增功能特性时，需在对应场景下新增特性手册，除了需要在特性代码仓维护文档内容外，还需要配置 openeuler/docs 仓对应场景的 `_toc.yaml` 文件。 +- 新增手册：新增功能特性时，需在对应场景下新增特性手册，除了需要在特性代码仓维护文档内容外，还需配置 openeuler/docs 仓对应场景的 `_toc.yaml` 文件。 - 修改手册：包括低错问题修复、章节增删等内容调整，直接在对应代码仓中更新文档即可。 ## 快速开始 -下面以服务器场景 openEuler 24.03 LTS SP2 版本的《oeAware用户指南》的修改为例，介绍如何进行文档开发。 +下面以 openEuler 24.03 LTS SP2 版本《oeAware用户指南》的修改为例，介绍文档开发流程。 ### 准备仓库 @@ -21,16 +21,16 @@ openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理， - openeuler/docs：文档总仓库，通过引用机制，集成所有特性文档至文档中心。 - openeuler/oeAware-manager：oeAware 特性源码仓，存储《oeAware用户指南》源文档。 -1. 准备 openeuler/docs 仓 +1. 准备 openeuler/docs 仓库 - (1) Fork openeuler/docs 仓。 + (1) Fork openeuler/docs 仓库。 - 找到并打开对应的[Repository的首页](https://gitee.com/openeuler/docs)。点击右上角的**Fork**按钮，按照指引，建立一个属于个人的云上 fork 仓库。 + 访问 [Repository 首页](https://gitee.com/openeuler/docs)。点击右上角的**Fork**按钮，按照指引，创建个人的云上 fork 仓库。 ![image](figures/forkdocs.jpg) (2) 克隆 openeuler/docs 仓库。 - 克隆 fork 仓库到本地，并将本地仓库与远程仓库关联。 + 克隆 fork 仓库到本地，并关联本地与远程仓库。 ```bash git clone https://gitee.com/wu-donger/docs.git @@ -42,15 +42,15 @@ openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理， (3) 切换分支。 - 依据所需修改文档的版本，切换到对应的分支。通常情况下，分支命名规则为`stable-版本号`。此处以25.03版本为例。 + 依据所需修改文档的版本，切换到对应的分支。通常情况下，分支命名规则为`stable-版本号`。此处以24.03 LTS SP2版本为例。 ```bash git checkout -b work2403sp2 upstream/stable-24.03_LTS_SP2 ``` -2. 准备 openeuler/oeAware-manager 仓 +2. 准备 openeuler/oeAware-manager 仓库 - 找到并打开源码仓的[Repository的首页](https://gitee.com/openeuler/oeAware-manager)。fork 仓库并克隆 fork 仓库到本地，切换目标分支。 + 访问 [Repository 首页](https://gitee.com/openeuler/oeAware-manager)。fork 仓库并克隆到本地，切换目标分支。 ```bash git clone https://gitee.com/wu-donger/oeAware-manager.git @@ -68,20 +68,20 @@ openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理， 1. 明确目标仓库 - 若首次添加特性指南时需明确： + 首次添加特性指南时，需明确： - 源文档存放仓库：特性源码仓库。 - 版本策略：通过分支或目录管理版本（推荐分支方式）。 - 示例：《oeAware用户指南》源文档存放仓库是 oeAware 特性的源码仓 openeuler/oeAware-manager，通过目录区分 openEuler 版本。 + 示例：《oeAware用户指南》的源文档存放在 oeAware 特性的源码仓库 openeuler/oeAware-manager，并通过目录区分 openEuler 版本。 相关约束和要求详见[SIG 组文档目录结构规范](./directory_structure_introductory.md#sig-组文档目录结构规范)。 - 此外，需为目标仓库配置文档 ci 和文档检视人员，可联系 DOC SIG maintainer 操作。 + 此外，需为目标仓库配置文档 CI 和文档检视人员，可联系 DOC SIG maintainer 操作。 2. 创建文件夹 - openEuler 的文档按照一定的目录结构组织，新增手册需要为其创建一个文件夹，存放实际内容文件和目录结构文件。《oeAware用户指南》的存放位置如下： + openEuler 文档遵循特定的目录结构。新增手册时，需创建一个文件夹来存放实际内容文件和目录结构文件。《oeAware用户指南》的存放路径如下： ```text ├─openeuler/oeAware-manager 仓 @@ -93,11 +93,12 @@ openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理， | └─_toc.yaml # 文档目录结构文件 ``` - > [!NOTE]说明 在仓库根目录下创建 /docs 目录，并在 /docs 目录下创建 zh/ 和 en/ 目录存放需发布至官网的中英文文档。 + > [!NOTE]说明 + > 在仓库根目录下创建 /docs 目录，并在其中创建 zh/ 和 en/ 目录存放需发布至官网的中英文文档。 3. 编辑目录结构文件`_toc.yaml` - 在步骤 1 所创建的文件夹中，新建一个`_toc.yaml`文件，以维护手册内各章节的展示逻辑。 + 在步骤 1 创建的文件夹中，新建一个`_toc.yaml`文件，以维护手册内各章节的展示逻辑。 ```yaml label: oeAware用户指南 # 手册名：《oeAware用户指南》 @@ -110,7 +111,7 @@ openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理， 4. 关联手册至对应场景 - 在 openeuler/docs 仓服务器场景的 [_toc.yaml](https://gitee.com/openeuler/docs/tree/stable-24.03_LTS_SP2/docs/zh/server/_toc.yaml) 文件中，添加对《oeAware用户指南》的引用。 + 在 openeuler/docs 仓库服务器场景的 [_toc.yaml](https://gitee.com/openeuler/docs/tree/stable-24.03_LTS_SP2/docs/zh/server/_toc.yaml) 文件中，添加对《oeAware用户指南》的引用。 ```yaml label: 服务器 # 场景名：服务器 @@ -144,44 +145,44 @@ sections: ### 提交变更 -1. 提交 openeuler/docs 仓的文档变更。 +1. 提交 openeuler/docs 仓库的文档变更。 - （1）提交变更并push到远程仓库。 + （1）提交变更并推送到远程仓库。 - ```bash - git add . + ```bash + git add . - git commit -m "提交原因" + git commit -m "提交原因" - git push origin work2403sp2 - ``` + git push origin work2403sp2 + ``` （2）创建PR。 - 在个人文档仓 Pull Requests 页面 `https://gitee.com/{your_org}/docs/pulls`，点击**新建Pull Request**创建PR。源分支选择 `{your_org}/docs/work2403sp2`，目的分支选择 `openeuler/docs/stable-24.03_LTS_SP2`。填写该PR的标题，并对修改内容进行简要说明，点击**创建Pull Request**。 + 在个人文档仓库的 Pull Requests 页面 `https://gitee.com/{your_org}/docs/pulls`，点击**新建Pull Request**创建PR。源分支选择 `{your_org}/docs/work2403sp2`，目的分支选择 `openeuler/docs/stable-24.03_LTS_SP2`。填写 PR 标题并简要说明修改内容，点击**创建Pull Request**。 （3）合入PR。 - 合入条件：文档流水线门禁通过，cla已签署，DOC SIG maintainer检视通过。 + 合入条件：文档流水线门禁通过，CLA 已签署，DOC SIG maintainer 检视通过。 - ![image](figures/approve.jpg) + ![image](figures/approve.jpg) -2. 提交 openeuler/oeaware-manager 仓的文档变更。 +2. 提交 openeuler/oeaware-manager 仓库的文档变更。 - （1）提交变更并push到远程仓库并创建 PR。 + （1）提交变更并推送到远程仓库，创建 PR。 - （2）合入PR。 + （2）合入 PR。 - 合入条件：SIG 组代码仓涉及文档变更的 PR，除代码仓原有的合入条件外，还需要文档流水线门禁通过，DOC SIG maintainer检视通过。
+ 合入条件：SIG 组代码仓涉及文档变更的 PR，除代码仓原有的合入条件外，还需要通过文档流水线门禁和 DOC SIG maintainer 审核。
- ![image](figures/sigdoc_approve.png) + ![image](figures/sigdoc_approve.png) - > [!NOTE]说明 - > DOC SIG maintainer 检视通过前会审视此 PR 是否需要转测试验收，检视测试流程详见：[文档检视测试流程](https://gitee.com/openeuler/docs/blob/stable-common/docs/zh/contribute/doc_review_test_process.md)。 + > [!NOTE]说明 + > DOC SIG maintainer 审核通过前会审视此 PR 是否需要转测试验收，检视测试流程详见：[文档检视测试流程](https://gitee.com/openeuler/docs/blob/stable-common/docs/zh/contribute/doc_review_test_process.md)。 3. 英文翻译 - 合入中文文档 PR 后，系统将自动生成翻译 issue 并排入处理队列，翻译人员会按顺序完成英文翻译并提交PR，需各 SIG 组 Maintainer 审核合入。如需加急翻译，请将对应中文文档 PR 链接同步至 DOC SIG 协调优先处理。 + 合入中文文档 PR 后，系统将自动生成翻译 issue 并排入处理队列，翻译人员将按顺序完成英文翻译并提交 PR，需各 SIG 组 Maintainer 审核并合入。如需加急翻译，请将对应中文文档 PR 链接同步至 DOC SIG 协调优先处理。 ## 更多 diff --git a/docs/zh/contribute/doc_tools_functions.md b/docs/zh/contribute/doc_tools_functions.md new file mode 100644 index 0000000000000000000000000000000000000000..72a95f2573cd2f04169c0f54e4af2acab11eafb3 --- /dev/null +++ b/docs/zh/contribute/doc_tools_functions.md @@ -0,0 +1,110 @@ +# 高级功能 + +## 文档预览 + +![Doc Preview](public_sys_resources/preview.gif) + +### 功能介绍 + +- 支持文档实时预览功能，可完整呈现单本手册内容，可将 Markdown 语法渲染为格式化文本，同时能够解析`_toc.yaml`文件，生成目录导航； +- 支持保存后刷新预览页面； +- 支持从预览页面打开对应的 Markdown 文件或 _toc.yaml 文件。 + +### 使用方法 + +1. 安装并启用本插件，打开 Markdown 文件； +2. 点击编辑器右上角的**D**字图标以打开预览页面； +3. 保存对 Markdown 文件的修改后，预览页面将自动刷新； +4. 修改关联的 _toc.yaml 文件后，预览页面将自动刷新。 + +## 目录生成 + +![toc generation](public_sys_resources/toc_generation.gif) + +### 功能介绍 + +- 自动生成目录：根据实际存在的 Markdown 文件，自动生成 _toc.yaml，避免手动维护目录结构； +- 同步标题：自动读取每个 Markdown 文件的一级标题（# ），作为目录项的 label； +- 去除无效项：如果 _toc.yaml 中的某些 href 指向的文件不存在，会自动移除这些无效项。 + +### 使用方法 + +1. 安装并启用本插件； +2. 右键点击目标目录，选择**Doc Tools** > **生成手册 _toc.yaml**； +3. 按需调整 label 值和章节顺序。 + +### 注意事项 + +- 只有带有一级标题（# 标题）的 Markdown 文件才会被收录。 + +## 批量检查链接可访问性 + +### 功能介绍 + +- 检测选中目录下的 Markdown 文档及 _toc.yaml 文件中的所有链接是否可访问； +- 以页面形式展示检测结果。 + +### 使用方法 + +1. 安装并启用本插件； +2. 右键点击目标目录，选择**Doc Tools** > **检测链接可访问性**； +3. 在打开的页面中按需勾选配置，点击**开始检查**； +4. 根据检查结果，修复失效链接或将误报链接加入白名单。 + +### 注意事项 + +- 私有或受限网络下的链接可能因网络原因被误判为无效，请以实际访问为准。 + +## 批量检查文件命名规范 + +### 功能介绍 + +- 批量检查选中目录下所有文件和子目录的命名规范：使用小写英文字母并以下划线连接单词； +- 以页面形式展示检测结果，方便用户处理命名不规范的文件。 + +### 使用方法 + +1. 安装并启用本插件； +2. 右键点击目标目录，选择**Doc Tools** > **检查目录、文件是否符合命名规范**； +3. 在打开的页面中查看检查结果，根据提示信息修改不符合规范的文件名或目录名。 + +### 注意事项 + +- 批量检查将遍历选中目录下的所有文件和子目录，可能需要一些处理时间； +- 修改文件名或目录名后，请同步更改其他文档中的相关链接。 + +## 检查中英文文档名称一致性 + +### 功能介绍 + +- 批量检查选中目录下中英文文档的文件名一致性； +- 通过页面展示检查结果，清晰标识缺少对应语言版本的文档。 + +### 使用方法 + +1. 安装并启用本插件； +2. 右键点击目标目录，选择**Doc Tools** > **检查中英文文档名称一致性**； +3. 在打开的页面中查看检查结果，根据提示信息补充缺失的文档，或修正不一致的文件名。 + +### 注意事项 + +- 批量检查会遍历选中目录下的所有 Markdown 文件，可能需要一些处理时间； +- 修改文件名后请同步更改其他文档中的相关链接。 + +## 生成链接锚点并复制 + +### 功能介绍 + +- 将选中的文本生成锚点并复制到剪贴板，方便后续使用。 + +### 使用方法 + +1. 安装并启用本插件； +2. 打开任意 Markdown 文件（`.md`）； +3. 选中标题文本； +4. 右击编辑区域，选择`Doc Tools` > `生成链接锚点并复制`。 + +### 注意事项 + +- 生成的锚点适用于 Vitepress 页面的锚点跳转； +- 通常情况下和大多数 Markdown 预览（如 VSCode 编辑器自带的 Markdown 预览）的锚点跳转一致，但在内容有一些符号的情况下存在一些差异，可能导致锚点在非 Vitepress 构建出的页面下不能跳转。 diff --git a/docs/zh/contribute/doc_tools_introduction.md b/docs/zh/contribute/doc_tools_introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..3f5f501baebca708af8711b63ad2d4c1e6a2259e --- /dev/null +++ b/docs/zh/contribute/doc_tools_introduction.md @@ -0,0 +1,52 @@ +# Doc Tools + +本插件集成了markdownlint、链接失效等多种常见文档问题的自动化检测修复功能，同时提供文档预览等功能，旨在提升文档开发体验。 + +## 安装 + +在 Visual Studio Code 中搜索插件并安装： + +![Doc Tools Installation](figures/install_doctools.png) + +## 功能总览 + +### 静态检查 + +| 名称 | 功能 | +| -----| ----| +| [Markdown Lint](./doc_tools_static_check.md#markdown-lint) | Markdown 语法检查 | +| [Tag Closed Check](./doc_tools_static_check.md#tag-closed-check) | Html 标签闭合检查 | +| [Link Validity Check](./doc_tools_static_check.md#link-validity-check) | 链接可访问性检查 | +| [Resource Existence Check](./doc_tools_static_check.md#resource-existence-check) | 资源有效性检查 | +| [Toc Check](./doc_tools_static_check.md#toc-check) | 目录文件规范性检查 | +| [CodeSpell Check](./doc_tools_static_check.md#codespell-check) | 单词拼写检查 | +| [Filename Check](./doc_tools_static_check.md#filename-check) | Markdown 文件命名规范检查 | +| [Punctuation Check](./doc_tools_static_check.md#punctuation-check) | 标点符号检查 | + +### 高级功能 + +| 名称 | 功能 | +| -----| ----| +| [文档预览](./doc_tools_functions.md#文档预览) | 预览 openEuler 文档风格的页面 | +| [目录生成](./doc_tools_functions.md#目录生成) | 自动生成 _toc.yaml | +| [批量检查链接可访问性](./doc_tools_functions.md#批量检查链接可访问性) | 批量检查选中目录下 Markdown 和 _toc.yaml 所有链接的可访问性 | +| [批量检查文件命名规范](./doc_tools_functions.md#批量检查文件命名规范) | 批量检查选中目录下文件和子目录的命名规范性 | +| [批量检查中英文文档名称一致性](./doc_tools_functions.md#检查中英文文档名称一致性) | 批量检查选中目录下 Markdown 中英文文档名称的一致性 | +| [生成链接锚点并复制](./doc_tools_functions.md#生成链接锚点并复制) | 将选中标题生成链接锚点并复制 | + +## 全局配置 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.scope` 或通过 `settings.json` 进行配置）： + +- `docTools.scope` + - 类型：`boolean` + - 说明：是否检查范围仅限于 `docs/zh` 和 `docs/en` 目录 + - 默认：`false` + +### 全局配置示例 + +```json +{ + "docTools.scope": false // 启用检查范围仅限于 docs/zh 和 docs/en 目录，默认检查项目全局文档 +} +``` diff --git a/docs/zh/contribute/doc_tools.md b/docs/zh/contribute/doc_tools_static_check.md similarity index 45% rename from docs/zh/contribute/doc_tools.md rename to docs/zh/contribute/doc_tools_static_check.md index b5c6f82e647102e7be6d4b6848683aad1b8fa9e9..e44127188320d9fa6c107b770ffd8e83cbc76e1a 100644 --- a/docs/zh/contribute/doc_tools.md +++ b/docs/zh/contribute/doc_tools_static_check.md @@ -1,44 +1,4 @@ -# Doc Tools - -本插件集成了markdownlint、链接失效等多种常见文档问题的自动化检测修复功能，同时提供文档预览等功能，旨在提升文档开发体验。 - -## 安装 - -在 Visual Studio Code 中搜索插件并安装： - -![Doc Tools Installation](figures/install_doctools.png) - -## 功能总览 - -| 名称 | 功能 | 执行时机 | 提示级别 | 提示语 | -| -----| ----| ----------| -------- | -------| -| [Markdown Lint](#markdown-lint) | Markdown 语法检查 | md 文件打开、保存、停止修改 1s 后 | warning | 具体的 markdownlint 规则 | -| [Tag Closed Check](#tag-closed-check) | Html 标签闭合检查 | md 文件打开、保存、停止修改 1s 后 | error | Unclosed html tag | -| [Link Validity Check](#link-validity-check) | 链接有效性检查（包含：1. 内链；2. 外链）| md 文件打开、 保存、停止修改 1s 后 | warning | Invalid link | -| [Resource Existence Check](#resource-existence-check) | 资源是否存在检查（包含：1. 内链；2. 外链）| md 文件打开、保 存、停止修改 1s 后 | warning | Non-existent resource| -| [Toc Check](#toc-check) | 目录文件检查（1. 目录中引用的文件需要存在；2. 每一篇 md 文档都需要在目录中进行维护） | \_toc.yaml 打开、保 存、停止修改 1s 后，md 文件打开后会检测是否加入 \_toc.yaml | error | Non-existent doc in toc | -| CodeSpell Check | 单词拼写检查 | md 文件打开、保存、停止修改 1s 后 | info | CodeSpell warning | -| [中英文标点混用检查](#中英文标点混用检查) | 中英文标点混用检查 | md 文件打开、保存、停止修改 1s 后 | warning | Mixing Punctuation | -| [中文标点冗余空格检查](#中文标点冗余空格检查) | 中文标点冗余空格检查 | md 文件打开、保存、停止修改 1s 后 | warning | Extra blank spaces | -| [目录生成](#目录生成) | 自动生成`_toc.yaml` | 点击**生成目录**按钮 | 不涉及 | 不涉及 | -| [文档预览](#文档预览) | 文档实时预览 | 点击**预览功能**按钮 | 不涉及 | 不涉及 | - -### 全局配置说明 - -插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.scope` 或通过 `settings.json` 进行配置）： - -- `docTools.scope` - - 类型：`boolean` - - 说明：是否检查范围仅限于 `docs/zh` 和 `docs/en` 目录 - - 默认：`false` - -#### 全局配置示例 - -```json -{ - "docTools.scope": false // 启用检查范围仅限于 docs/zh 和 docs/en 目录，默认检查项目全局文档 -} -``` +# 静态检查 ## Markdown Lint @@ -50,29 +10,25 @@ - 自动检测 Markdown 文件中的[格式问题](./markdownlint_rules.md)，如标题格式、列表缩进、空行等； - 可通过配置项灵活启用或禁用 lint 功能，并支持自定义 lint 规则，满足不同团队或个人的文档规范需求。 +- 支持一键修复功能，帮助用户一键修复所有 markdownlint 问题。 ### 使用方法 1. 安装并启用本插件，打开 Markdown 文件（`.md`），插件会自动对文件内容进行 lint 检查； -2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记上，查看详细的规则说明和建议； - -#### 默认规则 - -插件内置一套 markdownlint 默认规则（见 `config/markdownlint`），可根据实际需求通过配置覆盖。 +2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在底部问题面板，或将光标悬停在警告标记上，查看详细的规则说明和建议； +3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复所有 markdownlint 问题。 ### 配置说明 插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.markdownlint`或通过`settings.json`进行配置）： - `docTools.markdownlint` - - 类型：`boolean` - 说明：是否启用 Markdown lint 功能 - 默认：`true` - - `docTools.markdownlint.config` - 类型：`object` - - 说明：自定义 markdownlint 配置对象。若未设置，则使用插件内置的默认规则 + - 说明：自定义 markdownlint 配置对象。若未设置，则使用插件内置的默认规则。 #### 配置示例 @@ -100,14 +56,19 @@ ### 使用方法 -1. 安装并启用本插件，打开 Markdown 文件（`.md`），自动检查文件内容有效性； -2. 检查结果会以错误（Error）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在错误标记处，查看错误详情； +1. 安装并启用本插件，打开 Markdown 文件，自动检查文件内容有效性； +2. 检查结果会以错误（Error）的形式在编辑器中高亮显示，可在底部问题面板，或将光标悬停在错误标记处，查看错误详情； 3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复标签问题。 ### 快速修复说明 -- “转义字符替换”：自动将错误的转义标签替换为正确的 HTML 实体或标签； -- “闭合标签”：自动为未闭合的标签补全闭合部分。 +- \字符替换：适用于非 Html 标签嵌套的情况，会在对应的 Html 标签前加上 `\` 转义字符； +- <和>字符替换：适用于 Html 标签嵌套的情况，会将 `<` 和 `>` 替换为 `<` 和 `>`； +- 闭合标签：自动为未闭合的标签补全闭合部分。 + +### 注意事项 + +- 对于 Html 标签嵌套的情况，如`
`，请使用`<和>字符替换`方式进行修复，修复后为`<errorLabel>
`。 ### 配置说明 @@ -137,13 +98,16 @@ - `[文本](链接)` 形式的标准 Markdown 链接 - `` 形式的裸链接 - `` 形式的 HTML 链接 -- 支持跳过锚点链接（如 `#section`），并自动忽略链接中的锚点部分，仅校验主链接地址； +- 支持 HTTP/HTTPS 链接检测，自动忽略链接中的锚点部分（如 `#section`），仅校验主链接地址； +- 支持对相对路径的文件链接，进行本地文件存在性检查，并可检查锚点的有效性； +- 支持自定义 HTTP/HTTPS 链接检查白名单，避免对特定可信链接进行报错； - 支持通过配置项灵活启用或禁用该功能。 ### 使用方法 1. 安装并启用插件后，打开任意 Markdown 文件（`.md`），自动检测所有链接的有效性； -2. 无效链接会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板中，或将光标悬停在警告标记处，查看错误详情。 +2. 无效链接会以错误（Error）的形式在编辑器中高亮显示，可在底部问题面板中，或将光标悬停在警告标记处，查看错误详情； +3. 访问超时的链接会以警告（Warning）的形式在编辑器中高亮显示，可在底部问题面板中，或将光标悬停在警告标记处，查看错误详情。 ### 注意事项 @@ -151,6 +115,33 @@ - 某些私有或受限网络下的链接，可能因网络原因被误判为无效； - 对于本地文件链接，需确保路径正确且文件存在。 +### 配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.check.linkValidity`或通过`settings.json`进行配置）： + +- `docTools.check.linkValidity.enable` + - 类型：`boolean` + - 说明：是否启用链接有效性检查 + - 默认：`true` +- `docTools.check.linkValidity.only404.enable` + - 类型：`boolean` + - 说明：启用链接有效性检查只在链接无法访问时提示（可减少一些误报） + - 默认：`true` +- `docTools.check.url.whiteList` + - 类型：`array` + - 说明：检测链接白名单（添加后忽略对该链接的检查） + - 默认：`[]` + +#### 配置示例 + +```json +{ + "docTools.check.linkValidity.enable": true, + "docTools.check.linkValidity.only404.enable": true, + "docTools.check.url.whiteList": [] +} +``` + ## Resource Existence Check 检查 Markdown 文件中的资源链接（如图片、视频等）是否存在，帮助用户及时发现无效或丢失的资源引用。 @@ -219,68 +210,154 @@ } ``` -## 中英文标点混用检查 +## CodeSpell Check -![Punctuation Mix Check](public_sys_resources/biaodian_mix.gif) +检查 Markdown 文档中的单词拼写错误，帮助用户及时发现并修正。 ### 功能介绍 -- 自动检测 Markdown 中英文混用标点的情况（例如：中文内使用英文标点，或英文内使用中文标点）； -- 如需屏蔽此检测，可在该标点前后加空格（若后方紧跟其他标点符号，则无需额外空格）。 - - 例句1：添加 .png 后缀 - - 例句2：添加到 _toc.yaml。 - - 例句3：1. 这是一个有序列表 +- 自动扫描 Markdown 文档中的英文单词，检测拼写错误； +- 支持单词修正功能，用户可以根据提示选择正确的单词进行修正； +- 支持自定义忽略单词列表，用户可将特定单词加入白名单以避免误报； - 支持通过配置项灵活启用或禁用该功能。 ### 使用方法 -1. 安装并启用本插件，打开 Markdown 文件（`.md`），自动检查文档中的中英文标点混用情况； -2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记处，查看错误详情。 +1. 安装并启用本插件后，打开任意 Markdown 文件，自动检测文档中的单词拼写错误； +2. 检查结果会以提示（Info）的形式在编辑器中高亮显示，可在底部问题面板，或将光标悬停在错误标记处，查看错误详情。 +3. 通过 Quick Fix（快速修复）功能，可选择候选单词进行修改，或将误报单词添加至白名单。 -## 中文标点冗余空格检查 +### 配置说明 -![Ch Punctuation Spacing Check](public_sys_resources/zhbiaodian_space.gif) +插件支持以下配置项（可在 VSCode 设置中搜索 docTools.check.codespell 或通过 settings.json 进行配置）： -### 功能介绍 +- `docTools.check.codespell.enable` + - 类型：`boolean` + - 说明：是否启用单词拼写检查 + - 默认：`true` +- `docTools.check.codespell.whiteList` + - 类型：`array` + - 说明：单词白名单（添加后忽略对该单词的检查） + - 默认：`[]` -- 自动检测 Markdown 文件中的中文标点符号前后存在空格的错误； -- 支持通过配置项灵活启用或禁用该功能。 +### 配置示例 -### 使用方法 +```json +{ + "docTools.check.codespell.enable": true, + "docTools.check.codespell.whiteList": ["xxx"] +} +``` + +### 注意事项 -1. 安装并启用本插件，打开 Markdown 文件（`.md`），自动检查文档中的中文标点符号前后存在空格； -2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记处，查看错误详情； -3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复冗余空格问题。 +- 插件主要检测英文单词拼写，可能不适用于中文等非拉丁文字符； +- 某些专业术语或专有名词可能被误判为拼写错误，建议将其添加到白名单； +- 插件依赖于内置词典进行拼写检查，可能无法涵盖所有专业领域词汇。 -## 目录生成 +## Filename Check -![toc generation](public_sys_resources/toc_generation.gif) +检查文件和目录的命名规范性，以及中英文文档名称一致性，提升文档管理效率。 ### 功能介绍 -- 自动生成目录：根据实际存在的 Markdown 文件，自动生成`_toc.yaml`，避免手动维护目录结构； -- 同步标题：自动读取每个 Markdown 文件的一级标题（# ），作为目录项的 label； -- 去除无效项：如果`_toc.yaml`中的某些 href 指向的文件不存在，会自动移除这些无效项。 +- 支持检查 Markdown 文件名和目录名是否符合规范要求：使用小写英文字母并用下划线连接单词； +- 对于不符合规范的文件名，会在打开 markdown 文件时，在右下角弹出提示； +- 支持检查中英文文档文件名一致性，确保中英文文档一一对应； +- 当中英文文档文件名不一致时，会在打开 markdown 文件时，在右下角弹出提示； +- 支持通过配置项灵活启用或禁用相关功能。 ### 使用方法 -1. 安装并启用本插件； -2. 右键点击对应目录：选择“生成目录”命令，自动生成或更新此目录下的`_toc.yaml`； -3. 按需调整 label 值和章节顺序。 +1. 安装并启用本插件，在设置中勾选启用相关功能； +2. 打开 Markdown 文件后，若文件名不符合规范或中英文文档文件名不一致，右下角会弹出提示。 + +### 配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.check.name` 或通过 `settings.json` 进行配置）： + +- `docTools.check.name.enable` + - 类型：`boolean` + - 说明：是否启用文件/目录命名规范检查 + - 默认：`false` +- `docTools.check.name.whiteList` + - 类型：`array` + - 说明：文件/目录命名规范白名单（添加后忽略对该名称的检查） + - 默认：`[]` +- `docTools.check.nameConsistency.enable` + - 类型：`boolean` + - 说明：是否启用中英文文档名称一致性检查 + - 默认：`false` + +#### 配置示例 + +```json +{ + "docTools.check.name.enable": true, + "docTools.check.name.whiteList": ["README.md", "README_en.md"], + "docTools.check.nameConsistency.enable": true +} + +``` ### 注意事项 -- 只有带有一级标题（# 标题）的 Markdown 文件才会被收录。 +- 检查默认关闭，如需要相关功能请到设置中开启。 -## 文档预览 +## Punctuation Check -![Doc Preview](public_sys_resources/preview.gif) +检查 Markdown 文档中的标点符号使用规范，帮助用户发现并纠正标点符号错误，提升文档质量。 ### 功能介绍 -- 支持文档实时预览功能，可完整呈现单本手册内容，可将 Markdown 语法渲染为格式化文本，同时能够解析`_toc.yaml`文件，生成目录导航。 +- 自动扫描 Markdown 文档中的文本内容，检测标点符号使用是否规范； +- 支持检查中英文标点符号混用问题，如中文文本中使用英文标点，或英文文本中使用中文标点； +- 支持检查中文标点符号前后空格使用规范，中文标点前后不应有空格； +- 支持检查标点符号是否存在连续使用的情况； +- 支持检查手册/指南链接是否被书名号包裹； +- 标点符号错误会在编辑器以提示（Info）的形式高亮显示，可在底部问题面板，或将光标悬停在错误标记处，查看错误详情。 +- 支持通过配置项灵活启用或禁用相关功能。 ### 使用方法 -1. 安装并启用本插件，打开 Markdown 文件（`.md`）； -2. 点击编辑器右上角的**Doc Tools 预览功能**按钮，即可查看当前 Markdown 文件所属的完整手册内容。 +1. 安装并启用插件后，在设置中勾选启用相关功能； +2. 打开任意 Markdown 文件，插件将自动检测标点符号使用情况； +3. 检查结果会以提示（Info）的形式在编辑器中高亮显示，可在底部问题面板，或将光标悬停在错误标记处，查看错误详情。 + +### 配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.check.punctuation` 或通过 `settings.json` 进行配置）： + +- `docTools.check.punctuationBlankSpace.enable` + - 类型：`boolean` + - 说明：启用中文标点符号前后无空格检查 + - 默认：`false` +- `docTools.check.punctuationMixing.enable` + - 类型：`boolean` + - 说明：启用中英文标点符号混用检查 + - 默认：`false` +- `docTools.check.punctuationConsecutive.enable` + - 类型：`boolean` + - 说明：启用连续标点符号检查 + - 默认：`false` + +- `docTools.check.punctuationManualLink.enable` + - 类型：`boolean` + - 说明：启用手册/指南链接是否被书名号包裹检查 + - 默认：`false` + +#### 配置示例 + +```json +{ + "docTools.check.punctuationBlankSpace.enable": true, + "docTools.check.punctuationMixing.enable": true, + "docTools.check.punctuationConsecutive.enable": true, + "docTools.check.punctuationManualLink.enable": true +} +``` + +### 注意事项 + +- 检查默认关闭，如需要相关功能请到设置中开启； +- 因语句含义复杂，存在误报的情况。 diff --git a/docs/zh/contribute/documentation_writing_specifications.md b/docs/zh/contribute/documentation_writing_specifications.md index 620cff7d08acff1928042b5a17057b4b378ecb42..b20f1e30e224a1fc3ed5aa449f1cad47b75e73bc 100644 --- a/docs/zh/contribute/documentation_writing_specifications.md +++ b/docs/zh/contribute/documentation_writing_specifications.md @@ -130,7 +130,7 @@ installation_and_deployment.md #新增‘安装与部署’文档 【规则】如果有连续两个转义符，转义符之间要有空格 \{ \}。 -【规则】国际化：需同时提供中英文文档，可联系[ECHO](https://gitee.com/echo10111111)和[wu-donger](https://gitee.com/wu-donger)协助翻译；如需参与英文文档贡献，可参考[指南](./english_doc_contribute.md)。 +【规则】国际化：需同时提供中英文文档，可联系[ECHO](https://gitee.com/echo10111111)和[wu-donger](https://gitee.com/wu-donger)协助翻译；如需参与英文文档贡献，可参考[英文版](../../en/contribute/documentation_writing_specifications.md)。 ### 空格 @@ -156,7 +156,7 @@ installation_and_deployment.md #新增‘安装与部署’文档 ![alt 属性文本](图片地址 "可选标题") ``` -【规则】图片统一存放到文档同级目录下的 figures 文件夹中。例如，[《A-Tune用户指南》](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片，统一存储在 [A-Tune](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时，使用相对引用。 +【规则】图片统一存放到文档同级目录下的 figures 文件夹中。例如，[《A-Tune用户指南》](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片，统一存储在 [A-Tune](https://gitee.com/openeuler/docs-centralized/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时，使用相对引用。 【规则】请使用原创图片，避免存在知识产权侵权风险。