From 7f0cd061063e414475c1339c47c43305192c8cf9 Mon Sep 17 00:00:00 2001 From: yuluo-yx Date: Fri, 30 Aug 2024 11:03:13 +0800 Subject: [PATCH 1/2] [improve] add md-lint command and docs Signed-off-by: yuluo-yx --- .gitignore | 3 +++ .markdownlint-cli2.jsonc | 4 ++-- home/docs/community/document.md | 18 ++++++++++++++++++ .../current/community/document.md | 18 ++++++++++++++++++ home/package.json | 7 +++++-- 5 files changed, 46 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index bad93d68d15..ab833d335a0 100644 --- a/.gitignore +++ b/.gitignore @@ -54,3 +54,6 @@ node_modules application-dev.yml application-mysql.yml application-pg.yml + +# package.json +package.json diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index b1e0dd33d08..9c75e605b94 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -18,7 +18,6 @@ "config": { "default": true, "MD001": true, - "MD052": false, "MD003": false, "MD013": { "line_length": 600, @@ -35,7 +34,8 @@ "MD040": true, "MD045": false, "MD046": true, - "MD047": true + "MD047": true, + "MD052": false }, "ignore": [ "node_modules/", diff --git a/home/docs/community/document.md b/home/docs/community/document.md index b7f3af828d1..d0e33a972e7 100644 --- a/home/docs/community/document.md +++ b/home/docs/community/document.md @@ -44,6 +44,24 @@ This website is compiled using node, using Docusaurus framework components 5. In `home` directory run `npm run start-zh-cn`, you can visit to view the Chinese mode preview of the site 6. To generate static website resource files, run `npm run build`. The static resources of the build are in the build directory. +## Document Format Inspection + +In Apache Hertzbeat, all MD articles have to pass MD's [CI](https://github.com/apache/hertzbeat/blob/master/.github/workflows/doc-build-test.yml) inspection before they can be merged. The purpose is to keep the website looking nice and the formatting of the articles consistent. + +After you have written an MD article, you can execute the following command locally to check whether the content of the MD article meets the requirements, so as to reduce the workload of review and save your time: + +```shell +cd home && yarn + +yarn md-lint + +# If the documentation is wrong, you can use yarn md-lint-fix to fix it. +yarn md-lint-fix +``` + +For formatting rules for MD articles you can refer to: [Markdown-lint-rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) +MD format configuration file in the project: [.markdownlint-cli2.jsonc](https://github.com/apache/hertzbeat/blob/master/.markdownlint-cli2.jsonc) + ## Directory structure ```html diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/community/document.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/community/document.md index 7032d24688e..ede6c491427 100644 --- a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/community/document.md +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/community/document.md @@ -44,6 +44,24 @@ git clone git@github.com:/hertzbeat.git 5. 在`home`目录下运行 `npm run start-zh-cn`，您可以访问 查看站点的中文模式预览 6. 若要生成静态网站资源文件，请运行 `npm run build`。构建的静态资源位于 build 目录中。 +## 文档格式检验 + +在 Apache Hertzbeat 中，所有的 MD 文章都要通过 MD 的 [CI](https://github.com/apache/hertzbeat/blob/master/.github/workflows/doc-build-test.yml) 检测才能够合并，目的是为了保持文档官网的美观和文章格式的一致性。 + +在您编写了相关 MD 文章之后，您可以在本地执行以下命令，预先检查 MD 的文章内容是否符合要求，减少 review 的工作量，节省您的时间： + +```shell +cd home && yarn + +yarn md-lint + +# 如果文档错误，您可以使用 yarn md-lint-fix 修复 +yarn md-lint-fix +``` + +MD 文章的相关格式规则您可以参考：[Markdown-lint-rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) +项目中的 MD 格式配置文件：[.markdownlint-cli2.jsonc](https://github.com/apache/hertzbeat/blob/master/.markdownlint-cli2.jsonc) + ## 目录结构 ```html diff --git a/home/package.json b/home/package.json index 54cdb2d90cb..e503487cca5 100644 --- a/home/package.json +++ b/home/package.json @@ -13,7 +13,9 @@ "serve": "docusaurus serve", "clear": "docusaurus clear", "write-translations": "docusaurus write-translations", - "write-heading-ids": "docusaurus write-heading-ids" + "write-heading-ids": "docusaurus write-heading-ids", + "md-lint": "markdownlint-cli2 --config ../.markdownlint-cli2.jsonc \"./**/*.md\" \"#node_modules\"", + "md-lint-fix": "yarn md-lint --fix" }, "dependencies": { "@docusaurus/core": "2.3.1", @@ -39,7 +41,8 @@ "swiper": "7.4.1", "url-loader": "4.1.1", "workbox-routing": "6.5.3", - "workbox-strategies": "6.5.3" + "workbox-strategies": "6.5.3", + "markdownlint-cli2": "^0.13.0" }, "browserslist": { "production": [ From 368bfdd7ea9fccc962118dae777a752d38de57ca Mon Sep 17 00:00:00 2001 From: yuluo-yx Date: Fri, 30 Aug 2024 11:04:09 +0800 Subject: [PATCH 2/2] fix Signed-off-by: yuluo-yx --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index ab833d335a0..bad93d68d15 100644 --- a/.gitignore +++ b/.gitignore @@ -54,6 +54,3 @@ node_modules application-dev.yml application-mysql.yml application-pg.yml - -# package.json -package.json