docs: fix rendering of details-summary elements in the cli installation guide #4351
Conversation
bandantonio
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve,
derberg,
sambhavgupta0705 and
thulieblack
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughReplaces the CLI installation fragment from Markdown to MDX, deletes the old Markdown fragment, and updates the tutorial to import and render the new MDX component. The tutorial also restructures the installation section by removing a Remember block and adding a Prerequisites header with updated Node.js text. Changes
Sequence Diagram(s)(omitted — changes are documentation-only and do not alter runtime control flow) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Assessment against linked issues
Suggested labels
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
Status, Documentation and Community
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4351 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-4351--asyncapi-website.netlify.app/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
assets/docs/fragments/cli-installation.mdx (2)
29-34: Clarify Linux scope (Debian/Ubuntu) and suggest dependency note.
dpkgis the Debian package manager; the current copy implies generic Linux support. Consider scoping to Debian/Ubuntu (and derivatives) and adding a hint about resolving missing dependencies.Proposed tweak:
-You can install in Linux via `dpkg`, a debian package manager: +On Debian/Ubuntu and derivatives, install using `dpkg` (the Debian package manager): ```sh curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.deb sudo dpkg -i asyncapi.deb +# If dependencies are missing: +# sudo apt-get -f install--- `41-45`: **Minor Windows copy edits and consistency.** Hyphenate bitness and avoid redundant wording. ```diff -For Windows, install the appropriate installer and follow the default installation steps to complete the installation process. +For Windows, download the appropriate installer and follow the default steps. -- For 64-bit, download the [asyncapi.x64.exe](https://github.com/asyncapi/cli/releases/latest/download/asyncapi.x64.exe) -- For 32-bit, download the [asyncapi.x86.exe](https://github.com/asyncapi/cli/releases/latest/download/asyncapi.x86.exe) +- For 64‑bit, download [asyncapi.x64.exe](https://github.com/asyncapi/cli/releases/latest/download/asyncapi.x64.exe) +- For 32‑bit, download [asyncapi.x86.exe](https://github.com/asyncapi/cli/releases/latest/download/asyncapi.x86.exe)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
assets/docs/fragments/cli-installation.md(0 hunks)assets/docs/fragments/cli-installation.mdx(1 hunks)markdown/docs/tutorials/generate-code.md(1 hunks)
💤 Files with no reviewable changes (1)
- assets/docs/fragments/cli-installation.md
🧰 Additional context used
🪛 LanguageTool
assets/docs/fragments/cli-installation.mdx
[grammar] ~9-~9: There might be a mistake here.
Context: ...MacOS via brew: brew install asyncapi. - Using pkg: Each release of CLI produ...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ... that enables you to install this CLI as MacOS application. ```sh # Downloa...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Lighthouse CI
- GitHub Check: Test NodeJS PR - windows-latest
🔇 Additional comments (2)
assets/docs/fragments/cli-installation.mdx (2)
3-6: Good call using MDX for details/summary rendering.Wrapping OS-specific sections in native HTML
<details>/<summary>within an MDX fragment should resolve the embedding/rendering issue reported in #4344. The structure is clear and will be reusable across pages.Also applies to: 24-26, 48-53
7-12: Polish macOS section wording and casingThe macOS section has been updated for Apple’s preferred casing and clearer wording. The Homebrew formula is correctly available via
brew install asyncapi(no tap required).• File: assets/docs/fragments/cli-installation.mdx (lines 7–12)
-<summary>MacOS</summary> +<summary>macOS</summary> -- **Using `brew`**: You can install in MacOS via brew: `brew install asyncapi`. +- **Using Homebrew**: On macOS, install via Homebrew: `brew install asyncapi`. -- **Using `pkg`**: Each release of CLI produces a MacOS dedicated pkg file that enables you to - install this CLI as MacOS application. +- **Using the .pkg installer**: Each CLI release provides a dedicated macOS `.pkg` installer that lets you + install the CLI as a macOS application.
| You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 10 or higher and [npm](https://nodejs.org/en/download/package-manager/). | ||
|
|
||
| > **The AsyncAPI CLI v3.4.0 (released August 22, 2025) requires Node.js 16 or higher** | ||
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Fix contradictory Node.js version requirements (10+ vs 16+).
Line 58 states “Node.js 10 or higher,” but line 60 says v3.4.0 requires Node.js 16+. This will confuse users and can lead to installation failures. Align on a single minimum version (very likely 16+) across this fragment and the tutorial that imports it.
Apply this diff to align the requirements within this fragment (adjust if verification shows a different minimum):
-You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 10 or higher and [npm](https://nodejs.org/en/download/package-manager/).
+You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 16 or higher and [npm](https://nodejs.org/en/download/package-manager/).Optionally, avoid hardcoding a specific release/date in the callout to reduce future drift:
-> **The AsyncAPI CLI v3.4.0 (released August 22, 2025) requires Node.js 16 or higher**
+> As of the latest releases, the AsyncAPI CLI requires Node.js 16 or higher.Please verify the exact minimum Node.js version in the CLI repo (engines field / release notes) and update both this fragment and the tutorial accordingly. If helpful, use these queries:
🌐 Web query:
What is the minimum Node.js version required by AsyncAPI CLI v3.4.0? Verify via the official AsyncAPI CLI repo or release notes.
💡 Result:
The minimum Node.js version required by AsyncAPI CLI v3.4.0 is Node.js 16 or higher. This requirement is specified in the official AsyncAPI CLI installation guide, which states: “To use the AsyncAPI CLI tool, you must install NPM and Node.js version 16 or higher”[3]. This documentation is current as of January 2025, and applies to all 3.x releases including v3.4.0, unless a breaking change is mentioned in the release notes (none are noted for a higher requirement).
Additionally, the AsyncAPI Generator library (a core dependency) requires Node.js v18.12.0+ only from version 2.x onwards[1][4], but the official CLI guidance for v3.4.0 remains at Node.js 16+, as confirmed by the [package documentation and installation guides][3][1].
Summary of requirements for AsyncAPI CLI v3.4.0:
- Node.js: version 16 or higher[3]
- npm: no explicit minimum version specified for CLI itself, but the generator library recommends npm v8.19.0 or higher[1]
No evidence from the official CLI repository or release notes indicates a higher Node.js minimum for CLI v3.4.0 as of August 2025.
Citations:
- 1: https://www.asyncapi.com/docs/tools/generator/installation-guide
- 2: https://github.com/asyncapi/cli
- 3: https://www.asyncapi.com/docs/tools/cli/installation
- 4: https://github.com/asyncapi/generator/releases
- 5: https://github.com/asyncapi/cli/blob/master/package.json
- 6: https://www.npmjs.com/package/@asyncapi/nodejs-template
- 7: https://www.asyncapi.com/docs/migration/migrating-to-v3
- 8: https://cloud.google.com/bigtable/docs/release-notes
- 9: https://www.npmjs.com/package/@asyncapi/cli
- 10: https://community.chocolatey.org/packages?tags=asyncapi
Align Node.js requirement to 16+
We’ve confirmed that AsyncAPI CLI v3.4.0 requires Node.js 16 or higher. Update the fragment (and any tutorials importing it) to avoid confusion and installation failures.
• File: assets/docs/fragments/cli-installation.mdx
• Lines: 58–61
Apply this diff:
-You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 10 or higher and [npm](https://nodejs.org/en/download/package-manager/).
+You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 16 or higher and [npm](https://nodejs.org/en/download/package-manager/).
-> As of the latest releases, the AsyncAPI CLI requires Node.js 16 or higher.Also ensure the tutorial that pulls in this fragment reflects the same minimum.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 10 or higher and [npm](https://nodejs.org/en/download/package-manager/). | |
| > **The AsyncAPI CLI v3.4.0 (released August 22, 2025) requires Node.js 16 or higher** | |
| You can install the [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) with Node.js 16 or higher and [npm](https://nodejs.org/en/download/package-manager/). | |
| As of the latest releases, the AsyncAPI CLI requires Node.js 16 or higher. | |
| > **The AsyncAPI CLI v3.4.0 (released August 22, 2025) requires Node.js 16 or higher** |
🤖 Prompt for AI Agents
In assets/docs/fragments/cli-installation.mdx around lines 58 to 61, the Node.js
requirement still says "Node.js 10 or higher" while AsyncAPI CLI v3.4.0 requires
Node.js 16+. Update the fragment text to state Node.js 16 or higher (and any
associated npm requirement if needed), replace the highlighted note to reflect
the v3.4.0 requirement, and then search for any tutorials or docs that import
this fragment and update those pages to reference the same minimum Node.js 16+
requirement to keep all documentation consistent.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
markdown/docs/tutorials/generate-code.md (2)
6-6: Import placement looks good and keeps MDX stable.Having the MDX import right after frontmatter is consistent with common conventions and avoids tooling edge cases.
28-31: Prerequisites updated to Node.js 16+. LGTM.This aligns with the fragment and prevents installation failures on Node 10/12/14.
🧹 Nitpick comments (5)
assets/docs/fragments/cli-installation.mdx (5)
7-12: Fix platform naming and tighten macOS wording.Use the canonical “macOS” casing and simplify phrasing around the .pkg installer.
-<summary>MacOS</summary> +<summary>macOS</summary> -- **Using `brew`**: You can install in MacOS via brew: `brew install asyncapi`. -- **Using `pkg`**: Each release of CLI produces a MacOS dedicated pkg file that enables you to - install this CLI as MacOS application. +- **Using Homebrew**: Install on macOS with: `brew install asyncapi`. +- **Using a .pkg installer**: Each release provides a dedicated macOS .pkg installer you can use to + install the CLI as a macOS application.
29-34: Scope Linux instructions to Debian/Ubuntu-based distros.dpkg targets Debian-family systems; make that explicit to avoid misleading other distro users.
-You can install in Linux via `dpkg`, a debian package manager: +On Debian/Ubuntu-based distributions, install via `dpkg`:
13-22: Consider adding a brief checksum verification note for downloaded installers.Optional but recommended: after the curl commands, suggest verifying file integrity (for example, via a published SHA256 on the release page). Keeps users safer without changing flow.
If you want, I can draft a short “Verify download integrity” callout once you confirm whether the releases publish checksums for
.pkgand.deb.Also applies to: 31-34
1-1: Remove fragment-level title and promote the npm section to keep heading hierarchy clean under the host page.The host page already has “Installation guide” and “Prerequisites.” Dropping this extra H3 avoids a redundant “CLI Installation” heading; promoting “Using npm and Node.js” aligns levels.
-### CLI Installation +<!-- (intentionally left without a top-level heading; the host page provides it) --> @@ -#### Using npm and Node.js +### Using npm and Node.jsAlso applies to: 56-56
48-53: Optional: Prefer linking to official docs over the GitHub README.If there’s a canonical “CLI Installation” docs page, linking there reduces drift vs README anchors that can change.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
assets/docs/fragments/cli-installation.mdx(1 hunks)markdown/docs/tutorials/generate-code.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
assets/docs/fragments/cli-installation.mdx
[grammar] ~9-~9: There might be a mistake here.
Context: ...MacOS via brew: brew install asyncapi. - Using pkg: Each release of CLI produ...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ... that enables you to install this CLI as MacOS application. ```sh # Downloa...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Test NodeJS PR - windows-latest
🔇 Additional comments (3)
assets/docs/fragments/cli-installation.mdx (2)
3-54: Double-check that/render and toggle correctly inside .
Given the original bug, confirm the nested HTML works within the Remember component across themes and viewport sizes. If any styling/toggling issues appear, consider removing the Remember wrapper or moving the callout outside of the collapsible blocks.
Steps:
- In the PR preview, expand/collapse each OS section; verify focus states and keyboard toggling via Space/Enter on the summary element.
- Check mobile: ensure the hit area on the summary text is large enough and not obscured by the callout styling.
58-58: Node.js 16+ requirement aligned. LGTM.This matches the current CLI docs and resolves the earlier 10+ vs 16+ inconsistency.
markdown/docs/tutorials/generate-code.md (1)
32-32: Verify the embedded renders collapsible sections correctly.Since the fix hinges on embedding the MDX fragment, sanity-check the PR preview:
- Ensure all details/summary sections toggle as expected and inherit page typography.
- Inspect heading hierarchy: “Installation guide” (H2) → “Prerequisites” (H3) → fragment sections (ideally H3 after applying the heading tweak) → commands/code blocks.
- Keyboard/a11y: summary elements should be focusable and operable via keyboard.
If any issues show up, I can adjust the fragment headings or wrapper components accordingly.
|
/ptal |
|
@derberg @thulieblack @akshatnema @sambhavgupta0705 @anshgoyalevil @Mayaleeeee @TRohit20 Please take a look at this PR. Thanks! 👋 |
|
@TRohit20 can you please take a look |
|
@Shurtu-gal can you review this please from technical side of things |
|
Hey @thulieblack, before I review this I would like to know if we should still have code-generation using glee still there in website? Glee has been archived and plans are to remove glee related stuff from CLI as well: asyncapi/cli#1843 |
|
@sambhavgupta0705 @derberg do we? As far as I kno we are removing all glee related docs from website @Shurtu-gal |
|
anything Glee related should be removed from docs/website/wherever |
|
Then this PR should be closed ideally. |
|
@Shurtu-gal This PR has nothing to do with Glee. What's the point of closing it? |
6 participants
Related issue(s)
Fixes #4344
Summary by CodeRabbit