You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/05/18 00:57:44 UTC
[apisix-website] branch master updated: docs: add Chinese translation about blog-contributing-guide (#1094)

This is an automated email from the ASF dual-hosted git repository.

sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 26c94807d5c docs: add Chinese translation about blog-contributing-guide (#1094)
26c94807d5c is described below

commit 26c94807d5cbfa830c9a1d32dffc2f3a61bcd4ae
Author: tianjie <63...@users.noreply.github.com>
AuthorDate: Wed May 18 08:57:39 2022 +0800

    docs: add Chinese translation about blog-contributing-guide (#1094)
    
    * docs: add Chinese translation about blog-contributing-guide (#1078)
    
    Signed-off-by: lawrshen <la...@smail.nju.edu.cn>
---
 website/docs/general/blog-contributing-guide.md    |   3 +-
 .../current/blog-contributing-guide.md             | 207 +++++++++++++++++++++
 2 files changed, 209 insertions(+), 1 deletion(-)

diff --git a/website/docs/general/blog-contributing-guide.md b/website/docs/general/blog-contributing-guide.md
index 23961878e29..1484b411ada 100644
--- a/website/docs/general/blog-contributing-guide.md
+++ b/website/docs/general/blog-contributing-guide.md
@@ -95,6 +95,7 @@ authors:
     url: "Author's GitHub"
     image_url: "Author's Image URL"
   - name: "Translator/Technical Writer's name"
+    title: "Translator or Technical Writer"
     url: "Translator/Technical Writer's GitHub"
     image_url: "Translator/Technical Writer's Image URL"
 keywords:
@@ -143,7 +144,7 @@ Each post can have more than one tag. The available tags and explanations are as
 - **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 [five articles](/blog/tags/security/), and they generally have CVE-xxxxxxx in its title.
+- **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!
 
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
new file mode 100644
index 00000000000..91b92b64254
--- /dev/null
+++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/blog-contributing-guide.md
@@ -0,0 +1,207 @@
+---
+id: blog
+title: 博客贡献指南
+keywords:
+- API 网关
+- APISIX
+- Apache APISIX
+- 博客
+description: 如何在 Apache APISIX 官网提交或更新博客？
+---
+
+如需在 Apache APISIX 网站上进行撰写或更新[博客](/blog/)，请遵循本篇指南。
+
+如果你对已经发布的博客内容存有疑问，欢迎提交 [issue](/docs/general/submit-issue) 进行反馈。如果你有意愿，也可自己创建一个 [PR](/docs/general/contributor-guide/#open-a-pull-request) 对该问题进行修复。
+
+当前博客支持[中文](/zh/blog/)和[英文](/blog/)两种语言，你可以根据自己的熟悉的语言提交博客。目前中文和英文博客需要同时提交，否则在官网会出现未知错误，但是你不必担心，社区贡献者会在你提交博客之后翻译文章，届时你可以 Review 相应 PR。
+
+你可以在 `website/blog` 目录下根据年/月/日创建一个目录，并提交英文博客。
+
+例如：`website/blog/2022/03/01/apisix-integration-public-api-plugin.md` 该目录释义如下：
+
+- `apisix-integration-public-api-plugin.md` 是这篇博客的文件名，这篇博客的发布日期是 2022 年 3 月 1 日，
+- `website/blog/2022/03/01` 是该博客所在的目录。
+- `https://apisix.apache.org/blog/2022/03/01/apisix-integration-public-api-plugin` 是该博客 PR 合并后的 URL。
+
+:::note
+
+同样的，你可以在 `website/i18n/zh/docusaurus-plugin-content-blog` 目录下提交中文博客。
+
+:::
+
+## 博客类型
+
+你不但可以提交如何使用 Apache APISIX 的博客，而且也可以提交如何为 Apache APISIX 做贡献的博客。
+
+你也可以更新已经发布的博客，包括但不限于更新博客内容，修复 issues 中提到的链接错误、用词错误以及表述不清晰等问题。
+
+### 提交博客流程
+
+提交一篇新博客是为 Apache APISIX 做贡献的最好方式之一。Apache APISIX 项目的使用者和贡献者都可以从你的博客中学习经验。
+
+1. 首先你需要在正确的路径中存放新的博客文档。
+    1. 如果你用**英文**撰写博客，请在 `website/blog` 目录下新建一个 Markdown 文件。
+    2. 如果你用**中文**撰写博客，请在 `website/i18n/zh/docusaurus-plugin-content-blog` 目录下新建一个 Markdown 文件。
+    3. 如果你未能找到一个合适的目录匹配年月日，你可以新建一个文件夹来存放博客。
+
+2. 当你找到了一个存放你的博客的目录，你就可以在该目录中创建一个 Markdown 文件。请注意，文件名请使用英文，并且避免大写字母。Reviewers 可能会建议你改变文件名以提升 SEO（部分文件名含有大写字母，已经在 [#713](https://github.com/apache/apisix-website/issues/713) 中被修复）。
+
+3. 你可以通过编辑 Markdown 文件把文字、图片、图表添加到你的博客中。你可以从 [Markdown 指南](https://www.markdownguide.org/)了解更多关于 Markdown 格式的信息。
+    - 添加图片前请先将图片上传到[公共图片 CDN 服务](https://markdown-editor-chi.vercel.app/#/)然后在 Markdown 文件中添加图片链接。
+    - 表格及图片蕴涵了大量信息，我们很乐意看到它们。从经验来看小于等于4列的表格在网页上显得更加美观。
+
+4. 根据你新建的博客[创建一个 PR](/docs/general/contributor-guide/##创建一个-pr)。
+
+:::note
+
+你可以通过在本地构建网页环境检查你的修改。这可以确保在你提交 PR 之前没有任何错别字或遗留问题。虽然 Apache APISIX Website 会运行 CI 来检查并反馈这些错误，但更推荐优先在本地环境进行测试。具体构建流程请参考[构建网页环境](https://github.com/apache/apisix-website/blob/master/README.md)
+
+:::
+
+#### 配置博客元数据
+
+每一个博客源文件都包含了一个 YAML 前言或标题，并使用两行 `---` 与正文分分隔。
+
+元数据中包含了 `title`、`description`、`authors`、`tags` 和 `keywords` 等字段，部分内容可以参考的模板如下：
+
+##### 单作者模板
+
+如果你的博客只有一个作者可以使用以下模板：
+
+```markdown
+title: "Blog's Title"
+authors:
+  - name: "Author's Name"
+    title: "Author"
+    url: "Author's GitHub"
+    image_url: "Author's Image URL"
+keywords:
+- keywords 1
+- keywords 2
+- keywords 3
+- keywords 4
+- keywords 5
+description: Description of the post
+tags: [tag1,tag2,...,tagn]
+```
+
+##### 共同作者模板
+
+翻译和修改文章需要花费很多时间和精力，因此，你可以使用共同作者模板为博客添加多个作者。
+
+```markdown
+title: "Blog's Title"
+authors:
+  - name: "Author's Name"
+    title: "Author's title"
+    url: "Author's GitHub"
+    image_url: "Author's Image URL"
+  - name: "Translator/Technical Writer's name"
+    title: "Translator or Technical Writer"
+    url: "Translator/Technical Writer's GitHub"
+    image_url: "Translator/Technical Writer's Image URL"
+keywords:
+- keywords 1
+- keywords 2
+- keywords 3
+- keywords 4
+- keywords 5
+description: Description of the post
+tags: [tag1,tag2,...,tagn]
+```
+
+下面将详细介绍这些字段中的每一个：
+
+##### `authors`
+
+这是一个必填字段，当博客是由多人共同撰写时，必须使用这个字段以便表彰作者。 `authors` 字段由以下几部分构成：
+
+- `authors.name`：作者的姓名，例如张三：`name: "张三"`。
+- `authors.title`：作者的职位，例如文档工程师：`title: "Technical Writer"`。
+- `authors.url`：作者的 GitHub 主页，例如：`url: "https://github.com/yzeng25"`。
+- `authors.image_url`：作者的 GitHub 头像，例如：`authors.image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"`。
+
+##### `keywords`
+
+关键字是提升 SEO 优化文章排名的必需字段。
+
+在中文博客中，前三个关键字通常是 `API 网关`（英文博客中请使用 API Getway）、`APISIX` 和 `Apache APISIX`，后两个关键字与博客主题相关。
+
+##### `description`
+
+短描述是另外一个提升 SEO 优化网站排名的必需字段。
+
+对博客简短的概述就是一个好描述，通常描述的字符数在 150 到 170 之间即可。
+
+##### `tags`
+
+标签通常被用于文章的分类。
+
+每篇博客可以有多个标签。下面列举了一些常用的标签和相应解释，一篇博客通常会涵盖其中部分标签。如果无法找到适合的标签，请在提交 PR 时留下评论，我们将一起处理。
+
+:::note
+
+标签和应用标签的规则可能会随着时间而改变。
+
+:::
+
+- **Community**：和社区有关的内容，比如说："如何以代码之外形式给社区做贡献？"。
+- **Events**：和活动有关的内容，比如说：直播预告、活动预告、会议内容和项目会议内容。
+- **Interview**：例如，李杨博士访谈，《编程之夏》访谈。
+- **Practical Case**：包括要遵循的最佳实践。这很容易与 **Technology** 相混淆。文章的内容决定了该文章属于哪个标签。例如，"在xxx平台上运行 Apache APISIX" 属于 `Practical Case` 标签，而 "Apache APISIX 与 Envoy" 则属于 `Technology` 标签。
+- **Release**：版本发布的标签。请注意，博客文章中的版本发布说明是经过完善的，而对应仓库中的 `Release Note` 是由开发人员编写的。
+- **Security**：安全漏洞通知和解决安全漏洞的方法。目前有[六篇文章](/blog/tags/security/)，他们都同样有形如 CVE-xxxxxxx 的标题。
+- **Technology**：技术文章。需要与 **Practical Case** 区分（见上）。
+- **User Case**：关于在企业内使用 Apache APISIX 的博客，让我们知道你是如何使用 Apache APISIX 的！
+
+Reviewers 将在 Review 你的 PR 时帮助你选择合适的标签。
+
+##### 获取作者头像 URL
+
+1. 打开你的浏览器。
+2. 输入作者的 GitHub 页面的 URL，在 URL 结尾加一个 `.png`，例如：https://github.com/${author-username}.png。
+3. 这时将会打开作者的头像图片，请复制该图片的 URL。
+4. 复制图片 URL 到 `authors.image_url` 字段。
+
+![获取作者头像 URL](https://user-images.githubusercontent.com/49474499/155665803-198d1be0-2878-4c46-9ce1-7e39697eebe8.gif)
+
+#### 摘要
+
+```markdown
+title: "Blog's Title"
+---
+This is the summary.
+
+And this is also part of the summary.
+
+<!--truncate-->
+
+But this is not part of the summary.
+```
+
+你可以在你的文章中使用 `<!--truncate-->` 标志来决定哪部分内容以摘要形式显示在博客列表上。
+
+在 `<!--truncate-->` 以上的内容组成摘要。
+
+更多信息请参考 [Docusaurus 文档](https://docusaurus.io/docs/blog#blog-list)。
+
+##### 描述和摘要的区别
+
+描述和摘要的内容可能是一样的，那为什么我们要在两个字段上重复使用它们呢？
+
+描述主要目的是为了提高 SEO，并且主要由计算机阅读，而摘要则是让读者了解这篇博客的内容。
+
+### 修正错别字、格式化并保持更新
+
+你也可以通过修改或者更新现有的博客文章为 Apache APISIX 社区做出贡献。
+
+1. 首先你需要找到对应的博客文件。
+
+:::note
+
+中文博客则存放在 `website/i18n/zh/docusaurus-plugin-content-blog` 目录下，而英文博客则存放在 `website/blog` 目录下。
+
+:::
+
+2. 当你找到博客文件后，就可以修改对应的内容了。
+3. 提交一个带有更新信息的 [PR](/docs/general/contributor-guide#创建一个-pr)。