Skip to content

Commit

Permalink
docs: update blog contribution guidelines (#798)
Browse files Browse the repository at this point in the history
Co-authored-by: 琚致远 <juzhiyuan@apache.org>
Co-authored-by: Shivam Singh <shivam152002@gmail.com>
  • Loading branch information
3 people authored Dec 10, 2021
1 parent d1808f8 commit deb06ae
Showing 1 changed file with 41 additions and 6 deletions.
47 changes: 41 additions & 6 deletions website/docs/general/blog-contributing-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,11 @@ To add a new blog, please perform the following steps:

#### Blog's header information

##### Single author template

Our blogs start with a header sections containing fields such as `title`, `author`, `authorURL`, `authorImageURL`, `keywords`, `description`, and `tags`.

While `title` and `author` are starightforward, the other fields might be a bit confusing for first-time contributors. Explanations of each field is shown below. Please note that these fields could change over time.
While `title` and `author` are starightforward, the other fields might be a bit confusing for first-time contributors. Explanation of each field is mentioned below. Please note that these fields could change over time.

```markdown
title: "blog's title"
Expand All @@ -67,13 +69,37 @@ description: description of this blog
tags: [tag1]
```

##### Co-author template

[Co-author](https://docusaurus.io/docs/next/blog#blog-post-authors) feature is added, since translating and editing articles is also time-consuming, we would like to give credit to translators and technical writers as well.

```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"
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 this blog
tags: [tag1]
```

##### title

Required field, the title of the article, the standard expression in the form of `title: "title"`.
Required field for single author template, the title of the article, the standard expression in the form of `title: "title"`.

##### author

Required field, the article's author name, the standard form of expression for `author: "author"`.
Required field for single author template, the article's author name, the standard form of expression for `author: "author"`.

1. Community author: if you are willing to provide your real name, use your real name, if not, use your GitHub account name.

Expand All @@ -85,7 +111,16 @@ For business users or business cases, you can leave this item blank. Because Git

##### authorImageURL

The author's GitHub avatar, it is related with `authorURL`. For the same reason described above, this is an optional field. See below for how to get the avatar.
The author's GitHub avatar, it is related with `authorURL`. For the same reason described above, this is an optional field. See below for how to get the avatar.

#### authors

The required field for co-author template. When a blog is co-authored by 2 people, please use `authors` instead of `author` to give credits to both authors. `authors` consists of the following fields: `authors.name`, `authors.url`, `authors.title` and `authors.image_url`.

- `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 pages, 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"`.

##### keywords

Expand All @@ -110,9 +145,9 @@ Required field, tag, which is used to categorize the blog. Each post has and can

We can help authors to use a better category once a pull request is submitted.

#### How to get the authorImageURL
#### How to get the authorImageURL or authors.image_url

1. Open Chrome or your preffered browser.
1. Open Chrome or your preferred browser.
2. Enter the author's GitHub address to access the author's GitHub home page.
3. Right click on the author's avatar, and click "copy image address".
4. Paste image address to the authorImageURL field.
Expand Down

0 comments on commit deb06ae

Please sign in to comment.