This repository contains the sources of AsyncAPI website:
- It's powered by Next.js,
- It uses Tailwind CSS framework,
- It's build and deployed with Netlify,
- It uses Storybook as a frontend workshop and for documenting UI components.
Use the following tools to set up the project:
-
Fork the repository by clicking on
Forkoption on top right of the main repository. -
Open Command Prompt on your local computer.
-
Clone the forked repository by adding your own GitHub username in place of
<username>. For multiple contributions it is recommended to have proper configuration of forked repo.
git clone https://github.com/<username>/website/- Navigate to the website directory.
cd website- Install all website dependencies.
npm install- Run the website locally.
npm run dev-
Access the live development server at localhost:3000.
-
To run the storybook locally:
npm run dev:storybook- Access the live storybook development server at localhost:6006.
To bootstrap a new post, run this command:
npm run write:blogFollow the interactive prompt to generate a post with pre-filled front matter.
In order to prepare and spin up a Gitpod dev environment for our project, we configured our workspace through a .gitpod.yml file.
To spin up a Gitpod codespace, go to http://gitpod.io/#https://github.com/asyncapi/website.
- To build a production-ready website, run the following command:
npm run buildGenerated files of the website go to the .next folder.
- To build the production-ready storybook, run the following command:
npm run build:storybookGenerated files of the storybook go to the storybook-static folder.
After cloning repository to your local, perform the following steps from the root of the repository.
- Build the Docker image:
docker build -t asyncapi-website . - Start the container:
docker run --rm -it -v "$PWD":/async -p 3000:3000 asyncapi-website
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.
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:
-
Import the fragment at the top of the file (but below the frontmatter) using the following syntax:
import DesiredFragmentName from '@/assets/docs/fragments/fragmentYouWantToImport.md';
-
Add the imported fragment to the desired location in the Markdown file using the following syntax:
<DesiredFragmentName />
To lint the code, run the following command:
npm run lint
To fix the linting issues, run the following command:
npm run lint:fix
To lint the mdx files, run the following command:
npm run lint:mdx
To build and run a production-ready website, run the following command:
npm run build && npm run start
Generated files of the website go in the .next folder.
Start a local development server for the build tool using the configuration and environment variables set for local development with the Netlify CLI:
netlify dev
To start the server using the configuration and environment variables set for dev or all deploy contexts, run the following command:
netlify dev --context production
AsyncAPI Financial Summary page aims to provide transparency and clarity regarding the organization's financial activities. It serves as a platform to showcase how donations are accepted, different sponsorship options, and how the generated funds are utilized.
-
YAML files must be stored in the
config/financedirectory. -
Create separate folders for each year under
config/finance, such asconfig/finance/2023. Inside each year's folder, include two YAML files:Expenses.ymlandExpensesLink.yml. -
In
Expenses.yml, record expenses for each month, specifying theCategoryandAmount. -
In
ExpensesLink.yml, provide discussion links related to expense categories. -
When a new year begins, create a corresponding folder for that year under
config/financeand place the YAML files inside the folder for that specific year. For example, create a folder namedconfig/finance/2024for the year 2024 andconfig/finance/2025for the year 2025. Place the YAML file for each respective year inside its designated folder. -
Modify the years within the
scripts/finance/index.js,lib/getUniqueCategories.jsandcomponents/FinancialSummary/BarChartComponent.jsto handle data for different years effectively.
A case study is a special document that any end-user company can provide. An end-user company is a company that uses AsyncAPI to solve technical challenges. A case study is not a document where a vendor company can describe how they build their commercial AsyncAPI-based product. On the other hand, it is completely fine if a case study of some end-user mentions some commercial tools that helped them to work with AsyncAPI or event-driven architecture. An example of such a case can be a case study from an end-user where at some point, Confluent Schema Registry is mentioned in an explanation about schemas and runtime message validation.
A case study is documented in the form of a YAML file. Anyone can open a pull request with a new case study.
- YAML file must be located in
config/casestudies. - To make it easier for you to create such a YAML file you can use:
- All additional files for the case study, like complete AsyncAPI document examples, should be located in the
public/resources/casestudiesdirectory. - Company logo and other images that will be rendered in the website should be located in
public/img/casestudies.
Once you collect all information and create a case study, open a pull request. It must be authored or at least approved by a representative of the given company. Such a representative is probably already a contact person mentioned in the case study.
A case study becomes publicly available right after merging and rebuilding the website.
All AsyncAPI JSON Schema definition files are being served within the /definitions/<file> path. The content is being served from GH, in particular from https://github.com/asyncapi/spec-json-schemas/tree/master/schemas.
This is possible thanks to the following:
- A Netlify Rewrite rule located in the netlify.toml file, which acts as proxy for all requests to the
/definitions/<file>path, serving the content from GH without having an HTTP redirect. - A Netlify Edge Function that modifies the
Content-Typeheader of the rewrite response to becomeapplication/schema+json. This lets tooling, such as Hyperjump, to fetch the schemas directly from their URL.
Please find a flowchart explaining the flow this edge function should accomplish:
flowchart TD
Request(Request) -->schema-related{Is it requesting Schemas?}
schema-related -->|No| req_no_schemas[Let the original request go through]
req_no_schemas --> Response(Response)
schema-related -->|Yes| req_schemas[Fetch from GitHub]
req_schemas-->req_json{Was requesting a .json file?}
req_json -->|No| Response(Response)
req_json -->|Yes| response_status{Response Status?}
response_status -->|2xx| response_ok[OK]
response_status -->|304| response_cached[Not Modified]
response_status -->|Any other| response_ko
response_ok --> set_headers[Set Response Content-Type header to application/schema+json]
set_headers --> send_metric_success[Send success metric]
response_cached -- cached:true --> send_metric_success
response_ko --> send_metric_error[Send error metric]
send_metric_success -- file served from raw GH --> Response(Response)
send_metric_error --the errored response --> Response(Response)
This repository has the following structure:
├── .github # Definitions of GitHub workflows, pull request and issue templates
├── assets # Various assets
| ├── docs # Documentation assets
| | fragments # Documentations for CLI installation and contribution.
├── components # Various generic components such as "Button", "Figure", etc.
├── config # Transformed static data to display on the pages such as blog posts etc.
├── context # Various React's contexts used in website
├── locales # Translations for the website
├── markdown # Markdown files for the website
├── about # Markdown files for the /about page
├── blog # Markdown files for the blog posts
├── docs # Markdown files for the /docs/* pages
├── netlify # Contains Netlify serverless functions to run on Netlify
├── pages # Website's pages source. It includes raw markdown files and React page templates.
│ ├── about # Raw blog for /about page
│ ├── blog # Blog posts
│ ├── docs # Blog for /docs/* pages
│ └── tools # Various pages to describe tools
├── public # Data for site metadata and static blog such as images
├── scripts # Scripts used in the build and dev processes
├── styles # Various CSS files
├── templates # Various template markdown files
├── types # Various typeScript types used in the website
├── utils # Various JS code for preparing static data to render in pages
├── next.config.mjs # Next.js configuration file
├── README.md # Project's README file
├── tailwind.config.js # TailwindCSS configuration file
└── tsconfig.json # TypeScript configuration file
){kind=icon}
&style=flat){kind=icon}
This project's source code is licensed under the Apache License, Version 2.0. A copy of the license is available in LICENSE file.
This project's documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). A copy of the license is available in LICENSE-docs.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!