docs: enhance demo homepage with emojis and better organization #820
Conversation
Add emojis to section headers and reorganize content into four clear sections: - What You'll Find Here - Continuous Improvement - Technical Details - Support Improved readability and first-time user experience by better highlighting key features and resources.
|
""" WalkthroughThe changes update and expand documentation for the maxGraph project. The Introduction section in the Storybook demo markdown was extensively rewritten and structured, while the website documentation was updated to clarify the status and process of migrating stories from JavaScript to TypeScript. No code or API changes were made. Changes
Possibly related PRs
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
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. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
packages/website/docs/demo-and-examples.md (1)
24-24: Align migration phrasing across documentation
The update clarifies the origin and ongoing TypeScript migration. For consistency with other docs (e.g., “are being progressively migrated” in Introduction.mdx), consider:- - The stories were originally written in `JavaScript` and are progressively migrated to `TypeScript`. + - The stories were originally written in `JavaScript` and are being progressively migrated to `TypeScript`.packages/html/stories/Introduction.mdx (4)
52-53: Technical Details – migration context
The phrasing accurately conveys both the migration status and origin from mxGraph. Consider aligning tense and wording with related docs for a unified voice.
62-62: Refine wording for stronger impact
Replace “please feel free to open” with “open” or “submit” to strengthen the call to action:- If you find any issues, please feel free to open a sub-issue... + If you find any issues, open a sub-issue...🧰 Tools
🪛 LanguageTool
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, please feel free to open a ...(FIND_ENCOUNTER)
64-64: Correct pluralization in “discussion”
Change “create a new discussions” to “create a new discussion”:- If you have any questions or suggestions, create a new discussions... + If you have any questions or suggestions, create a new discussion...🧰 Tools
🪛 LanguageTool
[grammar] ~64-~64: The plural noun “discussions” cannot be used with the article “a”. Did you mean “a new discussion” or “new discussions”?
Context: ...ve any questions or suggestions, create a new discussions on the [GitHub repository](https://gith...(A_NNS)
67-67: Fix rendering tip spacing and path reference
Add a space after the closing span and update the file path for accuracy:- <span className="tip">Tip</span>To edit this page... + <span className="tip">Tip</span> To edit this page...Also update the path to
packages/html/stories/Introduction.mdxto match the actual location.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
packages/html/stories/Introduction.mdx(1 hunks)packages/website/docs/demo-and-examples.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
packages/html/stories/Introduction.mdx
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, please feel free to open a ...
(FIND_ENCOUNTER)
[grammar] ~64-~64: The plural noun “discussions” cannot be used with the article “a”. Did you mean “a new discussion” or “new discussions”?
Context: ...ve any questions or suggestions, create a new discussions on the [GitHub repository](https://gith...
(A_NNS)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: build
- GitHub Check: build (windows-2022)
- GitHub Check: build (macos-14)
- GitHub Check: build (ubuntu-22.04)
🔇 Additional comments (6)
packages/html/stories/Introduction.mdx (6)
31-31: Add engaging welcome header with emoji
Great addition of the emoji in the title—sets a welcoming tone and aligns with the PR’s goal of better organization and appeal.
33-33: Clarified Storybook demo overview
The expanded description succinctly explains Storybook usage and story organization—excellent for first-time users.
35-35: Enhanced “What You’ll Find Here” section
Adding an emoji and detailed list header improves visual hierarchy and readability.
37-40: Detailed feature list
The four bullet points clearly outline demo capabilities. The consistent formatting and bolding enhance scanability.
42-42: Clearly marked Continuous Improvement section
The rocket emoji and header draw attention to ongoing updates—well aligned with the PR objectives.
44-48: Expanded ongoing examples list
Great detail on what new examples cover; reinforces commitment to continuous improvement.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
packages/html/stories/Introduction.mdx (3)
35-41: Ensure consistent punctuation in list items.
The bullet points under "What You'll Find Here" currently lack terminating periods, which can feel inconsistent in Markdown. Consider adding a period at the end of each item for uniformity:- **Feature Demonstrations**: Each story focuses on specific capabilities, from basic graph rendering to advanced interactions + **Feature Demonstrations**: Each story focuses on specific capabilities, from basic graph rendering to advanced interactions. - **Combination Examples**: See how multiple features work together to create powerful graph applications + **Combination Examples**: See how multiple features work together to create powerful graph applications.
42-49: Consider unifying bullet voice and punctuation.
The "Continuous Improvement" section uses imperative verbs without periods, whereas other lists are descriptive. To enhance consistency, either:
- Add terminating periods to these bullets, or
- Rewrite them in a descriptive voice (e.g., "New examples are regularly added to demonstrate …").
58-64: Refine wording for opening sub-issues.
The phrase "open a sub-issue" can be aligned more closely with GitHub terminology. For example:If you find any issues, create a sub-issue under the [issue tracking all demo improvements](https://github.com/maxGraph/maxGraph/issues/505) issue.🧰 Tools
🪛 LanguageTool
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, open a sub-issue of the [is...(FIND_ENCOUNTER)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
packages/html/stories/Introduction.mdx(1 hunks)packages/website/docs/demo-and-examples.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/website/docs/demo-and-examples.md
🧰 Additional context used
🪛 LanguageTool
packages/html/stories/Introduction.mdx
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, open a sub-issue of the [is...
(FIND_ENCOUNTER)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: build
- GitHub Check: build (windows-2022)
- GitHub Check: build (macos-14)
- GitHub Check: build (ubuntu-22.04)
🔇 Additional comments (1)
packages/html/stories/Introduction.mdx (1)
31-34: Engaging header and introduction are clear and inviting.
The emoji and title formatting make for a friendly first impression, and the concise paragraph effectively explains the purpose of the demo.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
packages/html/stories/Introduction.mdx (1)
67-68: Add missing space after tip badge
Without a space, “TipTo” renders incorrectly. Update to:- <span className="tip">Tip</span>To edit this page… + <span className="tip">Tip</span> To edit this page…
🧹 Nitpick comments (3)
packages/html/stories/Introduction.mdx (3)
35-41: Ensure consistent punctuation in bullet points
The items under “What You’ll Find Here” are complete sentences but lack terminal punctuation. For consistency and clarity, consider adding a period at the end of each bullet. For example:- - **Feature Demonstrations**: Each story focuses on specific capabilities, from basic graph rendering to advanced interactions + - **Feature Demonstrations**: Each story focuses on specific capabilities, from basic graph rendering to advanced interactions.
50-57: Unify inline formatting for languages
You’ve italicized JavaScript and TypeScript, while using backticks for code identifiers likemxGraph. For consistency, consider using backticks for language names as well (e.g.,JavaScript,TypeScript), aligning with code styling elsewhere.
60-65: Consider using a bulleted list for support resources
To match the list-driven layout of earlier sections, you could transform the three support paragraphs into bullets. For example:## 🤝 Support - For detailed usage, see the [documentation](…). - If you find issues, create a sub-issue in [demo improvements](…). - For questions or suggestions, open a discussion in [GitHub Discussions](…).This would improve scannability.
🧰 Tools
🪛 LanguageTool
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, open a sub-issue of the [is...(FIND_ENCOUNTER)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/html/stories/Introduction.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
packages/html/stories/Introduction.mdx
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, open a sub-issue of the [is...
(FIND_ENCOUNTER)
🔇 Additional comments (2)
packages/html/stories/Introduction.mdx (2)
31-34: Clear, welcoming introduction
The new heading and opening paragraph effectively set context for first-time users, highlighting Storybook and the demo’s organizational structure. Great job improving readability.
42-49: Great overview of ongoing updates
The “Continuous Improvement” section clearly outlines future demo enhancements and links to deeper documentation. This will help users understand that the content is actively maintained.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
packages/html/stories/Introduction.mdx (1)
52-55: Maintain consistent verb tense.
For improved consistency, consider changing "The examples evolved" to "The examples have evolved" to match the present-perfect tense used elsewhere.
🧹 Nitpick comments (2)
packages/html/stories/Introduction.mdx (2)
1-28: Centralize styling for tip components.
Consider moving the inline<style>block for.tipand.tip-wrapperinto a shared global stylesheet or MDX theme configuration to ensure consistency across documentation and avoid duplication across stories pages.
60-63: Use stronger action verb.
Consider replacing "find any issues" (line 62) with "encounter any issues" to strengthen the call to action.🧰 Tools
🪛 LanguageTool
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, create a sub-issue under th...(FIND_ENCOUNTER)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/html/stories/Introduction.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
packages/html/stories/Introduction.mdx
[style] ~62-~62: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, create a sub-issue under th...
(FIND_ENCOUNTER)
🔇 Additional comments (4)
packages/html/stories/Introduction.mdx (4)
31-34: Clear and engaging introduction.
The new welcome heading and overview are concise and inviting for first-time users.
35-41: Organized feature overview.
The "What You'll Find Here" section effectively highlights demo capabilities with clear bullet points.
42-49: Continuous improvement emphasis.
The "Continuous Improvement" section aptly communicates ongoing updates and directs users to additional documentation.
66-68: Tip badge spacing is correct.
The space after the tip badge ensures proper rendering, and the instructions accurately reference the file path.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
packages/html/stories/Introduction.mdx (1)
50-61: Consistency: update verb tense for “evolved”
A past review suggested changing “The examples evolved” to “The examples have evolved” to maintain tense consistency with surrounding bullet items. Please adjust accordingly.
🧹 Nitpick comments (1)
packages/html/stories/Introduction.mdx (1)
62-69: Refine support wording for stronger tone
Consider replacing “If you find any issues” (line 66) with “If you encounter any issues” to better match the professional tone used elsewhere in the docs.🧰 Tools
🪛 LanguageTool
[style] ~66-~66: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, create a sub-issue under th...(FIND_ENCOUNTER)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/html/stories/Introduction.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
packages/html/stories/Introduction.mdx
[style] ~66-~66: Consider using a different verb to strengthen your wording.
Context: ...github.io/maxGraph/docs/intro). If you find any issues, create a sub-issue under th...
(FIND_ENCOUNTER)
🔇 Additional comments (3)
packages/html/stories/Introduction.mdx (3)
31-34: Well-structured introduction with emoji header
The new welcome section is clear and engaging. The “✨” emoji adds a friendly touch, and the concise description sets the right expectations for first-time users.
35-41: Clear “What You’ll Find Here” section
This bullet list effectively highlights key demo features, and the “🔍” emoji improves scannability. The concise phrasing makes it easy to skim.
42-49: “Continuous Improvement” section enhances confidence
Outlining ongoing additions and linking to deeper docs reassures users that the demo is actively maintained. The “🚀” emoji visually reinforces progress.
|
1 participant
Add emojis to section headers and reorganize content into four clear sections:
Improved readability and first-time user experience by better highlighting key features and resources.
Notes
Summary by CodeRabbit