Improve how people see spec in the website

[derberg]

Reason/Context

Even though AsyncAPI specification markdown file is located in the spec repo, for a better UX we make it available in the AsyncAPI website too. We have proper automation in place that makes sure they are in perfect sync, so no worries 🍺

But we just render markdown as it is and that is it.

It is looooong markdown.

When you jump from 2.0 to 2.1 majority of the content is the same. How one can spot what changed?

Go to release notes? yeah, sure, why not. But you need to know where to look for, and anyway we can do much better here!

Description

• Provide reference link to release notes. Somewhere on the top of every spec document we should also render link to GitHub release notes, where user also find link to more detailed article. So basically link from here -> here
• Have some kind of toogle (supported as query param), that once enabled, provides a kind of overlay, a smarter view, where in the rendered document, parts that are new/changed are highlighted. I don't know yet how nicely present removed parts

[AceTheCreator]

@derberg wanna assign this to me?

[derberg]

@AceTheCreator only if you want it 😄

[AceTheCreator]

@derberg guess it's all mine now 😀

[derberg]

@AceTheCreator enjoy! 😄 first research, explore possible options, share with community progress and some screen shots on how you see it and then implement 😉

[AceTheCreator]

@derberg Thanks for the heads-up, I'll definitely follow your suggested approach

[sambhavsaxena]

@derberg How about using an accordion for summarized release notes of every version like so: https://react-bootstrap.netlify.app/components/accordion/#accordion

and a link to detailed release notes at the footer of this accordion?

[derberg]

@sambhavsaxena the problem is we do not have such "summarized" release notes, only full release notes

[boyney123]

Just putting this here, not sure if it can help or not, but Codesandbox open-sourced a nice component that can help with docs.

https://codesandbox.io/post/sandpack-announcement

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: