fix: prevent empty <dd> tags in api.md from breaking website builds

[naaa760]

Description

• Fix empty <dd></dd> tags in generated api.md that break website builds
• Add missing docs.hbs template referenced in npm script
• Create custom main-index-dl.hbs and global-index-dl.hbs templates with conditional rendering
• Update docs generation script to include new template partials
• Regenerate api.md with fixed templates to eliminate empty description tags

Related issue(s)
Fixes #1737

Summary by CodeRabbit

• Documentation

  • Added new Handlebars templates to enhance API docs, including main and global definition-list indexes with signatures, optional descriptions, and composed page structure (header, body, member index, separators, members).
  • Cleaned up an API doc entry by consolidating and reformatting its description.

• Chores

  • Updated docs generation script to include the new templates and adjust rendering order.
  • No changes to public APIs.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1ac50b1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[asyncapi-bot]

What reviewer looks at during PR review

The following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.

1. PR Title: Use a concise title that follows our Conventional Commits guidelines and clearly summarizes the change using imperative mood (it means spoken or written as if giving a command or instruction, like "add new helper for listing operations")

   Note - In Generator, prepend feat: or fix: in PR title only when PATCH/MINOR release must be triggered.

2. PR Description: Clearly explain the issue being solved, summarize the changes made, and mention the related issue.

   Note - In Generator, we use Maintainers Work board to track progress. Ensure the PR Description includes Resolves #<issue-number> or Fixes #<issue-number> this will automatically close the linked issue when the PR is merged and helps automate the maintainers workflow.

3. Documentation: Update the relevant Generator documentation to accurately reflect the changes introduced in the PR, ensuring users and contributors have up-to-date guidance.

4. Comments and JSDoc: Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions, so others can easily understand and use the code.

5. DRY Code: Ensure the code follows the Don't Repeat Yourself principle. Look out for duplicate logic that can be reused.

6. Test Coverage: Ensure the new code is well-tested with meaningful test cases that pass consistently and cover all relevant edge cases.

7. Commit History: Contributors should avoid force-pushing as much as possible. It makes it harder to track incremental changes and review the latest updates.

8. Template Design Principles Alignment: While reviewing template-related changes in the packages/ directory, ensure they align with the Assumptions and Principles. If any principle feels outdated or no longer applicable, start a discussion these principles are meant to evolve with the project.

9. Reduce Scope When Needed: If an issue or PR feels too large or complex, consider splitting it and creating follow-up issues. Smaller, focused PRs are easier to review and merge.

10. Bot Comments: As reviewers, check that contributors have appropriately addressed comments or suggestions made by automated bots. If there are bot comments the reviewer disagrees with, react to them or mark them as resolved, so the review history remains clear and accurate.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[coderabbitai]

Walkthrough

Adds three Handlebars templates for docs generation (page layout, module index, global index) and updates apps/generator/package.json docs script to include the new templates; also regenerates apps/generator/docs/api.md with a minor formatting change to a description line.

Changes

Cohort / File(s)	Summary
Docs templates (Handlebars) apps/generator/docs/jsdoc2md-handlebars/docs.hbs, apps/generator/docs/jsdoc2md-handlebars/main-index-dl.hbs, apps/generator/docs/jsdoc2md-handlebars/global-index-dl.hbs	New Handlebars templates: docs.hbs composes page partials (header, body, member-index, separator, members); main-index-dl.hbs renders a Modules <dl> with signature links and optional descriptions; global-index-dl.hbs renders grouped globals <dl> with headings, signature links, optional descriptions, and first/last item control logic.
Docs generation config apps/generator/package.json	Updated docs script to register/include the new Handlebars templates/partials (main-index-dl.hbs, global-index-dl.hbs) used by jsdoc2md.
Generated docs apps/generator/docs/api.md	Regenerated API docs: removed an empty <dd>, consolidated and reformatted a description line to use inline code formatting (generate) to avoid newline/formatting issues.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title uses the conventional commit prefix “fix:” and directly describes the core issue of preventing empty tags in api.md from breaking website builds, which aligns with the primary change in the PR and is clear and concise for anyone scanning the history.
Linked Issues Check	✅ Passed	The pull request adds custom Handlebars templates with conditional rendering to eliminate empty tags, updates the docs generation script to include these templates, and includes the regenerated api.md showing the removed empty description tags, thereby directly fulfilling the objectives of linked issue #1737 to fix the newline-breaking in generated documentation.
Out of Scope Changes Check	✅ Passed	All modifications are focused on the documentation generation templates, the docs script, and the regenerated api.md to prevent empty tags, and there are no unrelated changes outside the scope of addressing the linked issue’s requirements.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a5d1dcf and 1ac50b1.

📒 Files selected for processing (3)

• apps/generator/docs/api.md (1 hunks)
• apps/generator/docs/jsdoc2md-handlebars/global-index-dl.hbs (1 hunks)
• apps/generator/docs/jsdoc2md-handlebars/main-index-dl.hbs (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• apps/generator/docs/api.md

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/generator/docs/jsdoc2md-handlebars/global-index-dl.hbs

🔇 Additional comments (1)

apps/generator/docs/jsdoc2md-handlebars/main-index-dl.hbs (1)

1-11: LGTM! Conditional rendering prevents empty <dd> tags.

The template correctly addresses the PR objectives by conditionally rendering the <dd> tag only when a description exists (Line 7). Placing the entire <dd> element on a single line within the conditional prevents the newline issue that was breaking website builds.

The structure is sound:

• @first/@last checks properly wrap the <dl> container
• Whitespace control with ~ is used appropriately throughout
• Triple braces {{{inlineLinks description}}} correctly render unescaped HTML for inline links

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

apps/generator/docs/jsdoc2md-handlebars/global-index-dl.hbs (1)

1-11: LGTM! Conditional rendering correctly prevents empty <dd> tags.

This template properly addresses the root cause of the website build failures by conditionally rendering the <dd> element only when a description exists (line 7). The structure correctly uses @first/@last helpers to manage the <dl> wrapper boundaries.

Minor observation: This template is nearly identical to main-index-dl.hbs except for the block helper ({{#globals kind=kind}} vs {{#modules}}) and title. Consider extracting the shared logic into a reusable partial if this pattern appears elsewhere in the future.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 08dd7a9 and a5d1dcf.

📒 Files selected for processing (4)

• apps/generator/docs/jsdoc2md-handlebars/docs.hbs (1 hunks)
• apps/generator/docs/jsdoc2md-handlebars/global-index-dl.hbs (1 hunks)
• apps/generator/docs/jsdoc2md-handlebars/main-index-dl.hbs (1 hunks)
• apps/generator/package.json (1 hunks)

🔇 Additional comments (3)

apps/generator/package.json (1)

21-21: LGTM! Script correctly integrates new templates.

The docs script has been properly updated to include the three new Handlebars templates (docs.hbs, main-index-dl.hbs, global-index-dl.hbs) as partials for jsdoc2md processing. The placement at the end of the partial list is appropriate.

apps/generator/docs/jsdoc2md-handlebars/docs.hbs (1)

1-5: LGTM! Standard documentation composition template.

This template correctly composes the API documentation page by including the standard jsdoc2md partials in the appropriate order (header, body, member-index, separator, members).

apps/generator/docs/jsdoc2md-handlebars/main-index-dl.hbs (1)

1-11: LGTM! Conditional rendering correctly prevents empty <dd> tags.

This template properly addresses the root cause of the website build failures by conditionally rendering the <dd> element only when a description exists (line 7). The structure correctly uses @first/@last helpers to manage the <dl> wrapper boundaries and follows the same pattern as global-index-dl.hbs for consistency.

[aasim-maverick]

Hey @naaa760, just saw your commits, the OP of gh-1737 expects the PR to include the fixed api.md.

Try running npm run docs and see if this is preventing </dd> from breaking into a new line. If yes, then add that to a commit too.

Edit: I think the tag still breaks into a new line.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud