id: blog title: Contribute a blog post keywords:
Please follow this guide while writing/updating blog posts on the Apache APISIX website.
Please submit an issue if you find any issues in the published blog posts. Also feel free to open a pull request to fix the issue yourself.
The blogs are written in both English and Chinese. 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 /apisix-website/blog/en/blog
directory, in which they are categorized by year, month and date.
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 /apisix-website/blog/zh/blog
directory and follow the same patterns described above.
You are encouraged to write blogs posts about how you use Apache APISIX or how you are contributing to Apache APISIX.
You can also update the existing blogs by updating the content or fixing issues like broken links and typos.
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.
To create a post, first find the right place to store it.
/apisix-website/blog/en/blog
directory./apisix-website/blog/zh/blog
directory.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).
You can add text, images, diagrams and charts to your post by adding them to the markdown file. You can learn more about formatting in markdown from The Markdown Guide.
Open a pull request with your new blog post.
Note: You can inspect your changes locally by building the website. This can ensure that there aren't any typos or issues left behind before you make a PR. We run CI checks to catch these errors but it is a recommended practice to test it locally.
To build the website locally, run:
cd website
yarn start
Each of the blog posts have a YAML front matter or a header before the content. These are enclosed within the two ---
in the markdown file.
The header section contains fields such as title
, description
, authors
, and tags
. A description of these fields and templates to copy are described below.
You can use template if your post only has a single author.
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]
Translating and editing articles consume time and effort and deserves credit. For this, you can use the co-author template to add multiple authors to the blog post.
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]
Each of these fields are described in detail below.
This is a required field to be used when the blog is co-authored by two or more people to give credit to both the authors. authors
field is composed of the following fields.
authors.name
: authors' names in plain text, for example: name: "John Doe"
.authors.title
: author's title in plain text, for example: title: "Technical Writer"
.authors.url
: authors' GitHub page, for example: url: "https://github.com/yzeng25"
.authors.image_url
: author's GitHub avatar, for example: authors.image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
.This is a required field used to enhance SEO performance.
Usually the first three keywords are “APISIX”, “Apache APISIX” and “API Gateway”, and the last two are specific to the blog post.
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 160. You can calculate with Character Statistics Software.
This is a required filed used to categorize the blog post.
Each post can have multiple tags. The tags used currently are given below and each post usually fits into one or more of these tags.
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.
Reviewers will help you find the right tags while reviewing your PR.
authors.image_url
field.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.
You can use the <!--truncate-->
marker in your posts to decide what will be shown as the post summary in the list of posts page.
Anything above <!--truncate-->
will be part of this summary.
You can learn more from the Docusaurus docs.
Summary and description could essentially be the same. Then why do we repeat them on two fields?
Well, the description's primary purpose is for SEO enhancement and is mainly read by computers where as the summary gives human readers an idea about the content of the blog post.
You can also make impactful contributions by fixing/updating the existing blog posts.
website/blog
directory and the Chinese blogs are located in website/i18n/zh/docusaurus-plugin-content-blog
directory.