docs: update documentation-guide (#1287)
* docs: update documentation-guide
diff --git a/website/docs/general/blog-contributing-guide.md b/website/docs/general/blog-contributing-guide.md
index 1484b41..22c4270 100644
--- a/website/docs/general/blog-contributing-guide.md
+++ b/website/docs/general/blog-contributing-guide.md
@@ -16,11 +16,11 @@
The blogs are written in both [English](/blog/) and [Chinese](/zh/blog/). Contributors are encouraged to write blogs in their preferred language. Translations can be handled later and you can review the pull request.
-English blogs are located in the `website/blog` directory, in which they are categorized by year, month and date.
+English blogs are located in the `/apisix-website/blog/en/blog` directory, in which they are categorized by year, month and date.
-For example, `website/blog/2021/11/22/develop-apisix-ingress-with-nocalhost-in-kubernetes.md` means that a blog named `develop-apisix-ingress-with-nocalhost-in-kubernetes.md` was published on November 22nd, 2021, and it is located in the `website/blog/2021/11/22` directory. Once it is reviewed and megered, the URL should be: `https://apisix.apache.org/blog/2021/11/22/develop-apisix-ingress-with-nocalhost-in-kubernetes`.
+For example, `/apisix-website/blog/en/blog/2022/03/01/apisix-integration-public-api-plugin.md` means that a blog named `develop-apisix-ingress-with-nocalhost-in-kubernetes.md` was published on November 22nd, 2021, and it is located in the `/apisix-website/blog/en/blog/2021/11/22` directory. Once it is reviewed and megered, the URL should be: `https://apisix.apache.org/blog/2022/03/01/apisix-integration-public-api-plugin/`.
-Similarly, Chinese blogs are located in `website/i18n/zh/docusaurus-plugin-content-blog` directory and follow the same patterns described above.
+Similarly, Chinese blogs are located in `/apisix-website/blog/zh/blog` directory and follow the same patterns described above.
## Areas to contribute
@@ -33,8 +33,8 @@
Writing a new blog post is one of the best ways to contribute to Apache APISIX. Users and contributors of the project will be able to learn from your experience through your content.
1. To create a post, first find the right place to store it.
- 1. If you are submitting a blog written in **English**, create a markdown file under the `website/blog` directory.
- 2. If you are submitting a blog written in **Chinese**, create a markdown file under the `website/i18n/zh/docusaurus-plugin-content-blog` directory.
+ 1. If you are submitting a blog written in **English**, create a markdown file under the `/apisix-website/blog/en/blog` directory.
+ 2. If you are submitting a blog written in **Chinese**, create a markdown file under the `/apisix-website/blog/zh/blog` directory.
3. If you don't find a directory that matches the year, month or date, you can create one yourself to store your post.
2. Once you find a place to store your post, you can create a markdown file in the directory. Note that the file name should be in English with no capitalized letters. Reviewers might suggest changing the file name to improve SEO (some of the file names contain capital letters and this is being fixed in [#713](https://github.com/apache/apisix-website/issues/713)).
@@ -129,7 +129,7 @@
This is also a required field used to enhance SEO performance.
-A brief summary of the blog post would be a good description. A good rule of thumb is to keep the number of characters in the description between 150 and 170.
+A brief summary of the blog post would be a good description. A good rule of thumb is to keep the number of characters in the description between 150 and 160. You can calculate with [Character Statistics Software](https://charactercalculator.com/).
##### tags
@@ -139,14 +139,11 @@
Each post can have more than one tag. The available tags and explanations are as follows. If none of the tags below fits, please leave a comment in your pull request, and we will handle it together. Please note that these tags and rules of applying tags could change over time.
-- **Community**: Everything related to community, for example, "How to contribute to an open source project without writing code?".
-- **Events**: Related to events, for example, live streams, event previews, meetups and project meetings.
-- **Interview**: For example, Dr. Yang Li interview, Summer of Programming interview.
-- **Practical Case**: Includes best practices to follow. This is easily confused with **Technology**. The content of the article determines which tag the post belongs to. For example, "Running Apache APISIX on the xxx platform" would belong to the Practical Case tag and "Apache APISIX vs Envoy" would belong to the Technology tag.
-- **Release**: Tag for release notes. Note that the release notes in blog posts are polished whereas inline release notes are written by developers.
-- **Security**: Security vulnerability notifications and methods to bypass security vulnerabilities. Currently there are [six articles](/blog/tags/security/), and they generally have CVE-xxxxxxx in its title.
-- **Technology**: Technical articles. Should not be confused with **Practical Case** (see above).
-- **User Case**: Posts about using Apache APISIX. Tell us how you are using Apache APISIX!
+- **Community**: Content related to community, community activities, and version release tags, such as: "How to contribute to the community in a form other than code?", live broadcast preview, event preview, meeting content and project meeting content.
+- **Security**: Security Vulnerability Notifications and Methods to Address Security Vulnerabilities. There are currently [six articles](/blog/tags/security/), and they all have the same title as CVE-xxxxxxx.
+- **Case Studies**: Blog about using Apache APISIX in the enterprise, let us know how you are using Apache APISIX!
+- **Plugins**: Blog related to Apache APISIX plugins.
+- **Ecosystem**: Content related to the surrounding ecology of Apache APISIX.
Reviewers will help you find the right tags while reviewing your PR.
diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/blog-contributing-guide.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/blog-contributing-guide.md
index a956f0b..2823e2b 100644
--- a/website/i18n/zh/docusaurus-plugin-content-docs/current/blog-contributing-guide.md
+++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/blog-contributing-guide.md
@@ -9,15 +9,15 @@
description: 如何在 Apache APISIX 官网提交或更新博客？
---
-如需在 Apache APISIX 网站上进行撰写或更新[博客](/blog/)，请遵循本篇指南。
+如需在 Apache APISIX 网站上进行撰写或更新[博客](https://apisix.apache.org/zh/blog/)，请遵循本篇指南。
如果你对已经发布的博客内容存有疑问，欢迎提交 [issue](/docs/general/submit-issue) 进行反馈。如果你有意愿，也可自己创建一个 [PR](/docs/general/contributor-guide/#open-a-pull-request) 对该问题进行修复。
-当前博客支持[中文](/zh/blog/)和[英文](/blog/)两种语言，你可以根据自己的熟悉的语言提交博客。目前中文和英文博客需要同时提交，否则在官网会出现未知错误，但是你不必担心，社区贡献者会在你提交博客之后翻译文章，届时你可以 Review 相应 PR。
+当前博客支持[中文](https://apisix.apache.org/zh/blog/)和[英文](https://apisix.apache.org/blog/)两种语言，你可以根据自己的熟悉的语言提交博客。目前中文和英文博客需要同时提交，否则在官网会出现未知错误，但是你不必担心，社区贡献者会在你提交博客之后翻译文章，届时你可以 Review 相应 PR。
-你可以在 `website/blog` 目录下根据年/月/日创建一个目录，并提交英文博客。
+你可以在 `/apisix-website/blog/en/blog` 目录下根据年/月/日创建一个目录，并提交英文博客。
-例如：`website/blog/2022/03/01/apisix-integration-public-api-plugin.md` 该目录释义如下：
+例如：`/apisix-website/blog/en/blog/2022/03/01/apisix-integration-public-api-plugin.md` 该目录释义如下：
- `apisix-integration-public-api-plugin.md` 是这篇博客的文件名，这篇博客的发布日期是 2022 年 3 月 1 日，
- `website/blog/2022/03/01` 是该博客所在的目录。
@@ -25,7 +25,7 @@
:::note
-同样的，你可以在 `website/i18n/zh/docusaurus-plugin-content-blog` 目录下提交中文博客。
+同样的，你可以在 `/apisix-website/blog/zh/blog` 目录下提交中文博客。
:::
@@ -35,13 +35,13 @@
你也可以更新已经发布的博客，包括但不限于更新博客内容，修复 issues 中提到的链接错误、用词错误以及表述不清晰等问题。
-### 提交博客流程
+## 提交博客流程
提交一篇新博客是为 Apache APISIX 做贡献的最好方式之一。Apache APISIX 项目的使用者和贡献者都可以从你的博客中学习经验。
1. 首先你需要在正确的路径中存放新的博客文档。
- 1. 如果你用**英文**撰写博客，请在 `website/blog` 目录下新建一个 Markdown 文件。
- 2. 如果你用**中文**撰写博客，请在 `website/i18n/zh/docusaurus-plugin-content-blog` 目录下新建一个 Markdown 文件。
+ 1. 如果你用**英文**撰写博客，请在 `/apisix-website/blog/en/blog` 目录下新建一个 Markdown 文件。
+ 2. 如果你用**中文**撰写博客，请在 `/apisix-website/blog/zh/blog` 目录下新建一个 Markdown 文件。
3. 如果你未能找到一个合适的目录匹配年月日，你可以新建一个文件夹来存放博客。
2. 当你找到了一个存放你的博客的目录，你就可以在该目录中创建一个 Markdown 文件。请注意，文件名请使用英文，并且避免大写字母。Reviewers 可能会建议你改变文件名以提升 SEO（部分文件名含有大写字母，已经在 [#713](https://github.com/apache/apisix-website/issues/713) 中被修复）。
@@ -58,13 +58,13 @@
:::
-#### 配置博客元数据
+### 配置博客元数据
每一个博客源文件都包含了一个 YAML 前言或标题，并使用两行 `---` 与正文分分隔。
元数据中包含了 `title`、`description`、`authors`、`tags` 和 `keywords` 等字段，部分内容可以参考的模板如下：
-##### 单作者模板
+#### 单作者模板
如果你的博客只有一个作者可以使用以下模板：
@@ -85,7 +85,7 @@
tags: [tag1,tag2,...,tagn]
```
-##### 共同作者模板
+#### 共同作者模板
翻译和修改文章需要花费很多时间和精力，因此，你可以使用共同作者模板为博客添加多个作者。
@@ -112,7 +112,7 @@
下面将详细介绍这些字段中的每一个：
-##### `authors`
+#### `authors`
这是一个必填字段，当博客是由多人共同撰写时，必须使用这个字段以便表彰作者。 `authors` 字段由以下几部分构成：
@@ -121,19 +121,19 @@
- `authors.url`：作者的 GitHub 主页，例如：`url: "https://github.com/yzeng25"`。
- `authors.image_url`：作者的 GitHub 头像，例如：`authors.image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"`。
-##### `keywords`
+#### `keywords`
关键字是提升 SEO 优化文章排名的必需字段。
在中文博客中，前三个关键字通常是 `API 网关`（英文博客中请使用 API Getway）、`APISIX` 和 `Apache APISIX`，后两个关键字与博客主题相关。
-##### `description`
+#### `description`
-短描述是另外一个提升 SEO 优化网站排名的必需字段。
+短描述是另外一个提升 SEO 优化网站排名的必需字段，需要包括用户需要这篇文章时，可能会使用的搜索关键字。
-对博客简短的概述就是一个好描述，通常描述的字符数在 150 到 170 之间即可。
+对博客简短的概述就是一个好描述，通常描述的字符数在 150 到 160 之间即可。你可以通过[字符统计软件](https://www.eteste.com/)进行计算。
-##### `tags`
+#### `tags`
标签通常被用于文章的分类。
@@ -145,18 +145,15 @@
:::
-- **Community**：和社区有关的内容，比如说："如何以代码之外形式给社区做贡献？"。
-- **Events**：和活动有关的内容，比如说：直播预告、活动预告、会议内容和项目会议内容。
-- **Interview**：例如，李杨博士访谈，《编程之夏》访谈。
-- **Practical Case**：包括要遵循的最佳实践。这很容易与 **Technology** 相混淆。文章的内容决定了该文章属于哪个标签。例如，"在xxx平台上运行 Apache APISIX" 属于 `Practical Case` 标签，而 "Apache APISIX 与 Envoy" 则属于 `Technology` 标签。
-- **Release**：版本发布的标签。请注意，博客文章中的版本发布说明是经过完善的，而对应仓库中的 `Release Note` 是由开发人员编写的。
+- **Community**：社区、社区活动有关的内容以及版本发布的标签，比如说："如何以代码之外形式给社区做贡献？"，直播预告、活动预告、会议内容和项目会议内容。
- **Security**：安全漏洞通知和解决安全漏洞的方法。目前有[六篇文章](/blog/tags/security/)，他们都同样有形如 CVE-xxxxxxx 的标题。
-- **Technology**：技术文章。需要与 **Practical Case** 区分（见上）。
-- **User Case**：关于在企业内使用 Apache APISIX 的博客，让我们知道你是如何使用 Apache APISIX 的！
+- **Case Studies**：关于在企业内使用 Apache APISIX 的博客，让我们知道你是如何使用 Apache APISIX 的！
+- **Plugins**：与 Apache APISIX 插件相关的博客。
+- **Ecosystem**：与 Apache APISIX 周边生态相关的内容。
Reviewers 将在 Review 你的 PR 时帮助你选择合适的标签。
-##### 获取作者头像 URL
+#### 获取作者头像 URL
1. 打开你的浏览器。
2. 输入作者的 GitHub 页面的 URL，在 URL 结尾加一个 `.png`，例如：https://github.com/${author-username}.png。
@@ -165,7 +162,7 @@
-#### 摘要
+### 摘要
```markdown
title: "Blog's Title"
@@ -185,13 +182,13 @@
更多信息请参考 [Docusaurus 文档](https://docusaurus.io/docs/blog#blog-list)。
-##### 描述和摘要的区别
+#### 描述和摘要的区别
描述和摘要的内容可能是一样的，那为什么我们要在两个字段上重复使用它们呢？
描述主要目的是为了提高 SEO，并且主要由计算机阅读，而摘要则是让读者了解这篇博客的内容。
-### 修正错别字、格式化并保持更新
+## 保持文章更新
你也可以通过修改或者更新现有的博客文章为 Apache APISIX 社区做出贡献。
diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
index bd8864c..27b90b8 100644
--- a/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
+++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
@@ -27,7 +27,7 @@
- 写作时使用主动语态，不要使用被动语态。
- 如果是英译中的文档，需要符合中文阅读习惯，并确保句子通顺，无语病。
-:::note
+:::note 注意
如果部分内容翻译后没有必要或者表达无意义，请根据上下文进行调整或删改。纯机翻没有意义，文档需要给予阅读者清晰明确的指引，而不是毫无意义的文字。
@@ -70,11 +70,22 @@
- 长代码需要进行格式化处理，让用户直观地看到命令全文。
- 命令与返回结果需要使用不同的代码块进行展示。
- 使用 [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。以下是每个 admonitions 的使用场景：
- - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
- - Note：想要突出的一般信息，该信息需要用户关注的。
- - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
- - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
- - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+ - Note（注意）：为用户提供基于其他内容的额外提示。
+ - Tip（提示）：想要突出的一般信息，该信息需要用户关注的。
+ - Important（重要）：用户需要关注的一般信息，该信息可能需要用户特别注意。
+ - Warning（警告）：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+ - Danger（危险）：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+
+ 示例如下：
+
+ ```shell
+ ::note 注意
+
+ 为用户提供基于其他内容的额外提示。
+
+ :::
+ ```
+
- 请使用表格描述恰当的内容。
- 请尽量保证表格内容不包含空置的行和列。
- 表格中的描述需要简洁。
