Improve bit Boilerplate project template docs (#11556)

[ysmoradi]

closes #11556

Summary by CodeRabbit

Release Notes

• Documentation

  • Significantly expanded getting-started guide with five new tutorial stages: .NET Aspire, MAUI/Blazor Hybrid, Messaging, Diagnostic Modal, and Passwordless Authentication, including setup instructions and cross-stage references.

• Chores

  • Updated build configuration warning suppressions.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Documentation and configuration updates for the boilerplate project template. The primary change reorganizes and expands AI generation prompts, introducing four new stages (Aspire, MAUI/Blazor Hybrid, Messaging, Diagnostic Modal) and relocating WebAuthn content. Build configuration adds a warning suppression token, and HTML files receive clarifying comments about component reuse.

Changes

Cohort / File(s)	Summary
Getting-Started Prompts Expansion src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md	Restructured and expanded Stages 19–23: Stage 19 becomes ".NET Aspire" with deployment guidance, Stage 20 introduces ".NET MAUI / Blazor Hybrid" with platform details, Stage 21 covers "Messaging" infrastructure, Stage 22 addresses "Diagnostic Modal", Stage 23 consolidates "WebAuthn and Passwordless Authentication (Advanced)". Includes extensive instructional content, examples, configuration guidance, and cross-stage references throughout.
HTML Documentation Comments src/Client/Boilerplate.Client.Maui/wwwroot/index.html, src/Client/Boilerplate.Client.Web/wwwroot/index.html	Added inline comments clarifying that LoadingComponent.razor markup was copied into HTML files due to lack of Razor rendering support. No functional or structural changes.
Build Configuration src/Directory.Build.props	Added ASPIREPROXYENDPOINTS001 warning suppression token to MSBuild NoWarn property.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• The primary change is content documentation with consistent, repetitive structure across new stages (homogeneous pattern reduces review complexity)
• HTML comment additions are trivial
• Build configuration change is minimal and localized

Poem

🐰 New stages bloom in prompts divine,
From Aspire clouds to MAUI lines,
Messaging hops through signals bright,
Diagnostics gleam, WebAuthn's might—
A boilerplate with wings takes flight! ✨

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'Improve bit Boilerplate project template docs (#11556)' directly aligns with the main changes in this PR. The changeset focuses on enhancing documentation for the bit Boilerplate project template, including expanded AI-generated getting-started prompts with new stages, updated index.html comments for client projects, and build configuration updates. The title accurately summarizes the primary intent and content of the changes.
Linked Issues check	✅ Passed	The pull request successfully addresses the linked issue #11556's objective to improve and enhance documentation for the bit Boilerplate project template. The changes include comprehensive expansions to the getting-started prompts file with new stages (Aspire, MAUI/Blazor Hybrid, Messaging, Diagnostic Modal, WebAuthn), updates to multiple index.html files with clarifying comments, and a build configuration update for Aspire warnings. All coding-related enhancements directly support improved documentation and developer guidance.
Out of Scope Changes check	✅ Passed	All changes in the pull request are properly scoped to documentation enhancements for the bit Boilerplate project template. The modifications include prompt file expansions, HTML comment additions for clarity, and a necessary build warning suppression for Aspire integration. No unrelated code changes or feature implementations outside the documentation improvement objective are present.

---

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: 6

🧹 Nitpick comments (2)

src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md (2)

812-812: Fix markdown list indentation inconsistencies and bare URLs.

Static analysis flagged several markdown formatting violations in the new content blocks, particularly in Stages 19–21:

• List indentation errors: Lines 852, 902–904, 908–916, 961–964 have inconsistent indentation (expected 0–2 spaces for list levels; actual varies from 1–7)
• Bare URLs: Lines 815 ("https://aspire.dev"), 871 ("https://aspire.dev"), 919 ("https://bitplatform.dev/demos") should be wrapped in markdown link syntax [text](url)

These issues may cause rendering inconsistencies or fail linting in CI pipelines.

Standardize list indentation to 2 spaces per nesting level and wrap bare URLs in markdown link syntax. For example:

-   - **Key Benefits**:
-     - Better performance compared to the web version
+   - **Key Benefits**:
+       - Better performance compared to the web version

And:

-   - Developers can learn about Aspire capabilities at https://aspire.dev
+   - Developers can learn about Aspire capabilities at [https://aspire.dev](https://aspire.dev)

Also applies to: 852-852, 902-916, 961-964

---

732-732: Apply grammar and style improvements.

Several copyediting issues detected:

• Line 732: "2 phase deployment" → "2-phase deployment" (hyphenate compound adjectives per English grammar)
• Line 732: "github" → "GitHub" (proper capitalization/trademark)
• Line 811: "awesome dashboard" → consider replacing with more formal term (e.g., "comprehensive," "powerful")
• Line 891: "TCP etc)" → "TCP, etc.)" (period required before closing paren)
• Line 994: "very careful" → consider stronger alternatives (e.g., "exceptionally careful," "absolutely critical")

Apply these diffs:

-2 phase deployment, where first project gets built and uploaded to github/azure dev-ops artifacts,
+2-phase deployment, where first project gets built and uploaded to GitHub/Azure DevOps artifacts,

-     - **Development**: Provides an awesome dashboard for monitoring your app during development
+     - **Development**: Provides a comprehensive dashboard for monitoring your app during development

-   - **Broader OS Support**: The Windows output works on Windows 7, 8, 10, and 11  
-     - In contrast, `Boilerplate.Client.Maui`'s Windows output only works on Windows 10 and 11
+   - **Broader OS Support**: The Windows output works on Windows 7, 8, 10, and 11  
+     - In contrast, `Boilerplate.Client.Maui`'s Windows output only works on Windows 10 and 11

-     - (Access to local devices through TCP etc)
+     - (Access to local devices through TCP, etc.)

-   - **Responsible Component**: `DiagnosticSpacer` component is responsible for handling the clicks and opening the modal
+   - **Responsible Component**: `DiagnosticSpacer` component handles the clicks and must not be removed, as it is responsible for opening the modal

Also applies to: 811-811, 891-891, 994-994

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between a8f2503 and 95808d7.

📒 Files selected for processing (4)

• src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md (21 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Maui/wwwroot/index.html (2 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Web/wwwroot/index.html (2 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Directory.Build.props (1 hunks)

🧰 Additional context used

🪛 LanguageTool

src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md

[grammar] ~732-~732: Use a hyphen to join words.
Context: ... applied in backend CD though is using 2 phase deployment, where first project ge...

(QB_NEW_EN_HYPHEN)

---

[uncategorized] ~732-~732: The official name of this software platform is spelled with a capital “H”.
Context: ...irst project gets built and uploaded to github/azure dev-ops artifacts, then in anothe...

(GITHUB)

---

[grammar] ~738-~738: Ensure spelling is correct
Context: ...roceed to Stage 16 (Automated Testing - Unitigration Tests)?"** --- ## Stage 16: Automated...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[style] ~811-~811: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...ent**: - Development: Provides an awesome dashboard for monitoring your app durin...

(AWESOME)

---

[style] ~891-~891: In American English, abbreviations like “etc.” require a period.
Context: ...es (Access to local devices through TCP etc) - Code Compatibility: Code that...

(ETC_PERIOD)

---

[style] ~994-~994: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...**: Emphasize that developers should be very careful not to break the Layout structure in a ...

(EN_WEAK_ADJECTIVE)

🪛 markdownlint-cli2 (0.18.1)

src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md

812-812: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

815-815: Bare URL used

(MD034, no-bare-urls)

---

852-852: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

---

871-871: Bare URL used

(MD034, no-bare-urls)

---

902-902: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

903-903: Unordered list indentation
Expected: 2; Actual: 5

(MD007, ul-indent)

---

904-904: Inconsistent indentation for list items at the same level
Expected: 2; Actual: 3

(MD005, list-indent)

---

904-904: Unordered list indentation
Expected: 0; Actual: 3

(MD007, ul-indent)

---

908-908: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

---

909-909: Unordered list indentation
Expected: 2; Actual: 3

(MD007, ul-indent)

---

910-910: Unordered list indentation
Expected: 2; Actual: 3

(MD007, ul-indent)

---

913-913: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

---

914-914: Inconsistent indentation for list items at the same level
Expected: 1; Actual: 2

(MD005, list-indent)

---

914-914: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

915-915: Inconsistent indentation for list items at the same level
Expected: 1; Actual: 3

(MD005, list-indent)

---

915-915: Unordered list indentation
Expected: 0; Actual: 3

(MD007, ul-indent)

---

916-916: Inconsistent indentation for list items at the same level
Expected: 1; Actual: 3

(MD005, list-indent)

---

916-916: Unordered list indentation
Expected: 0; Actual: 3

(MD007, ul-indent)

---

919-919: Bare URL used

(MD034, no-bare-urls)

---

961-961: Unordered list indentation
Expected: 2; Actual: 5

(MD007, ul-indent)

---

962-962: Unordered list indentation
Expected: 2; Actual: 5

(MD007, ul-indent)

---

963-963: Unordered list indentation
Expected: 4; Actual: 7

(MD007, ul-indent)

---

964-964: Inconsistent indentation for list items at the same level
Expected: 5; Actual: 3

(MD005, list-indent)

---

964-964: Unordered list indentation
Expected: 2; Actual: 3

(MD007, ul-indent)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build and test