Skip to content

Commit

Permalink
docs: replace duplicated content with reusable fragments (#3269)
Browse files Browse the repository at this point in the history
Co-authored-by: Lukasz Gornicki <[email protected]>
  • Loading branch information
bandantonio and derberg authored Oct 9, 2024
1 parent 662ec26 commit 2e31739
Show file tree
Hide file tree
Showing 21 changed files with 106 additions and 203 deletions.
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,24 @@ After cloning repository to your local, perform the following steps from the roo

Now you're running AsyncAPI website in a development mode. Container is mapped with your local copy of the website. Whenever you make changes to the code, the website will refresh and changes visible in localhost:3000.
## Use shared Markdown fragments
To minimize the duplication of content and make it easier to maintain, there are shared fragments you can use when working with Markdown files. These fragments are stored in the `/assets/docs/fragments` directory.
To include a fragment in a Markdown file:
1. Import the fragment at the top of the file (but below the frontmatter) using the following syntax:
```md
import DesiredFragmentName from '@/assets/docs/fragments/fragmentYouWantToImport.md';
```
1. Add the imported fragment to the desired location in the Markdown file using the following syntax:
```md
<DesiredFragmentName />
```
## Lint the code
To lint the code, run the following command:
```
Expand Down
14 changes: 14 additions & 0 deletions assets/docs/fragments/contribution-notes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:

1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our [AsyncAPI Docs Board](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Docs contributor questions

Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`alequetzalli`](https://github.com/alequetzalli) πŸ™.
25 changes: 6 additions & 19 deletions assets/docs/fragments/how-to-contribute.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,10 @@
## How to contribute to AsyncAPI Docs

Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:

1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).

2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.

4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Tag me in your AsyncAPI Doc PRs

Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!
## How to contribute to AsyncAPI Docs

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

### Talk to me

I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
1 change: 1 addition & 0 deletions assets/docs/fragments/talk-to-me.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
19 changes: 6 additions & 13 deletions markdown/blog/2023-April-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ authors:
byline: In April 2023, the AsyncAPI documentation experienced significant growth with 8,889 sessions and 4,575 unique users, including 2,895 new users.
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Docs Report - April 2023
In April 2023, the AsyncAPI documentation experienced significant growth with **8,889 sessions** and **4,575 unique users**, including **2,895 new users**. April was a strong month for our expanding docs community.

Expand Down Expand Up @@ -109,18 +112,8 @@ style DC fill:#E1FEC1,stroke:#000000,stroke-width:2px;
---

## How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
19 changes: 6 additions & 13 deletions markdown/blog/2023-Q1-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ authors:
excerpt: Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem.
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Documentation Report - Q1 2023

During Q1 2023, AsyncAPI Docs had **26,875 sessions** and **13,506 unique users**.
Expand Down Expand Up @@ -170,18 +173,8 @@ style G fill:#FF6EC7,stroke:#000000,stroke-width:2px;
---

## How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
20 changes: 6 additions & 14 deletions markdown/blog/2023-Q4-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ authors:
excerpt: In Q4, AsyncAPI docs had primary engagement across the tutorials and reference content buckets.
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Documentation Report - Q4 2023
As a core maintainer of AsyncAPI Docs, I (Alejandra Quetzalli) volunteer to write periodic updates about the AsyncAPI Docs ecosystem. The goal is to keep the community informed about what's going on in docs and how docs contributors collaborate with other areas in AsyncAPI Initiative.

Expand Down Expand Up @@ -94,19 +97,8 @@ A --> H
---

### How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a **huge** help that benefits the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself and questions on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!
5. Send me a DM in Slack!

#### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question, and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

#### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
22 changes: 7 additions & 15 deletions markdown/blog/2023-july-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ authors:
photo: /img/avatars/canela-ale.webp
link: https://www.linkedin.com/in/alejandra-quetzalli/
byline: In July 2023, the AsyncAPI documentation had 7,443 sessions and 3,895 unique users, including 2,345 new users.
---
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Docs Report - July 2023

Expand Down Expand Up @@ -87,19 +90,8 @@ A --> H
---

### How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself and questions on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!
5. Send me a DM in Slack!

#### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

#### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
20 changes: 6 additions & 14 deletions markdown/blog/2023-june-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ authors:
byline: In June 2023, the AsyncAPI documentation had 7,827 sessions and 4,203 unique users, including 2,566 new users.
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Docs Report - June 2023
In June 2023, the AsyncAPI documentation had **7,827 sessions** and **4,203 unique users**, including **2,566 new users**, showing consistent engagement within our vibrant docs community.

Expand Down Expand Up @@ -120,19 +123,8 @@ style K fill:#C1F9F7,stroke:#000000,stroke-width:2px;
---

### How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!
5. Send me a DM in Slack!

#### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

#### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
19 changes: 6 additions & 13 deletions markdown/blog/2023-may-docs-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ authors:
byline: In May 2023, the AsyncAPI documentation had 9,453 sessions and 4,876 unique users, including 2,895 new users.
---

import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
import TalkToMe from '@/assets/docs/fragments/talk-to-me.md';

# AsyncAPI Docs Report - May 2023
In May 2023, the AsyncAPI documentation had **9,453 sessions** and **4,876 unique users**, including **2,895 new users**, highlighting the increasing interest and engagement within our vibrant docs community. May was a busy month in our expanding docs community!

Expand Down Expand Up @@ -71,18 +74,8 @@ style DA fill:#E1FEC1,stroke:#000000,stroke-width:2px;
---

## How to contribute to AsyncAPI Docs
Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❀️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our Docs GH Board [here](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Tag me in your AsyncAPI Doc PRs
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`/alequetzalli`](https://github.com/alequetzalli) πŸ™.
Did you know that you can contribute Docs to AsyncAPI as well?
<ContributionNotes />

### Talk to me
I want and need to listen πŸ‘‚πŸ½ to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. πŸ“ There's a lot of good work ahead, but **you** determine _our content roadmap_ because the OSS community needs should always come first.✨
<TalkToMe />
Loading

0 comments on commit 2e31739

Please sign in to comment.