Overview
This repository contains the sources of AsyncAPI website:
Requirements
Use the following tools to set up the project:
Run locally
-
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.
Compose new blog post
To bootstrap a new post, run this command:
npm run write:blogFollow the interactive prompt to generate a post with pre-filled front matter.
Spin up Gitpod codespace
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.
Build
To build a production-ready website, run the following command:
npm run buildGenerated files of the website go to the .next folder.
Case studies
Overview
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.
How to add a case study
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.
JSON Schema definitions
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.
Project structure
This repository has the following structure:
├── .github # Definitions of GitHub workflows, pull request and issue templates
├── 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
├── css # Various CSS files
├── lib # Various JS code for preparing static data to render in pages
├── 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
├── next.config.js # Next.js configuration file
├── netlify # Code that runs on Netlify
│ ├── edge-functions # Netlify Edge-Functions code
├── postcss.config.js # PostCSS configuration file
└── tailwind.config.js # TailwindCSS configuration file
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!