docs: fix numbering and standardize UI bolding in Asgardeo onboarding#5917
Open
KethniiImasha wants to merge 8 commits intowso2:masterfrom
Open
docs: fix numbering and standardize UI bolding in Asgardeo onboarding#5917KethniiImasha wants to merge 8 commits intowso2:masterfrom
KethniiImasha wants to merge 8 commits intowso2:masterfrom
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughEditorial updates to two Asgardeo get-started docs: reworded intro and headings, adjusted organization and user creation steps (added an email "Register" step and inline image), removed a curl example, clarified roles/terminology and links; no code, API, or functional control-flow changes. (37 words) Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Around line 16-18: Update the note text to use end‑user terminology and
address the reader as "you": replace "You can also use a social login method to
create your account." with phrasing that uses "sign-in" and "you" (e.g., "You
can also sign in using a social sign-in method to create your account.") so the
UI wording follows the "sign-in" convention and directly addresses the reader;
apply the same change where the same phrasing appears elsewhere in the file (the
other occurrence noted).
- Line 12: Remove the new image reference line that adds "! [Sign up to
Asgardeo]({{base_path}}/assets/img/get-started/sign-up-to-asgardeo.png){:
width="700" style="display: block; margin: 0; border: 0.3px solid lightgrey;}"
from the create-asgardeo-account.md content, or replace it only after you
explicitly confirm the asset exists and is accessible; locate the exact markdown
image string in the diff and either delete it or await/attach verification
before re-adding.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
en/asgardeo/docs/get-started/create-asgardeo-account.md (1)
12-12:⚠️ Potential issue | 🟠 MajorUnresolved: image reference still present without confirmed asset availability.
The new
sign-up-to-asgardeo.pngimage was flagged in the previous review as requiring explicit confirmation that the asset exists and is accessible. The issue remains open.Run the following to confirm the asset exists in the repository:
#!/bin/bash # Check if the referenced image asset exists fd "sign-up-to-asgardeo.png" --type f🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` at line 12, The markdown includes a reference to sign-up-to-asgardeo.png in create-asgardeo-account.md; verify the asset actually exists in the repository (search for the exact filename sign-up-to-asgardeo.png) and if it does not, either add the image asset to the assets/img/get-started/ folder or replace the markdown image reference with an existing image (or remove it) so the file no longer points to a missing asset; update the markdown in create-asgardeo-account.md to use the confirmed asset path or remove the image tag accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Around line 19-22: The tip's body text is not indented under the admonition
header ("!!! tip \"Access the Asgardeo Console\"") causing the paragraph to
render outside the tip box; fix by indenting the descriptive line ("As an
organization owner or administrator, you can manage...") so it is a child of the
admonition (same 4-space indentation as the inline code line) and remove the
extra blank line between that paragraph and the code URL so both lines are
contained inside the tip block.
- Around line 16-17: The admonition text after the "!!! note" is not indented
correctly so it renders outside the note; locate the "!!! note" block and
increase the following line's indentation by 4 spaces (so it's 4 spaces relative
to the "!!!" marker — in this nested list case make the content 7 spaces total)
to nest the paragraph inside the note (adjust the line immediately following the
"!!! note" marker).
---
Duplicate comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 12: The markdown includes a reference to sign-up-to-asgardeo.png in
create-asgardeo-account.md; verify the asset actually exists in the repository
(search for the exact filename sign-up-to-asgardeo.png) and if it does not,
either add the image asset to the assets/img/get-started/ folder or replace the
markdown image reference with an existing image (or remove it) so the file no
longer points to a missing asset; update the markdown in
create-asgardeo-account.md to use the confirmed asset path or remove the image
tag accordingly.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
en/asgardeo/docs/get-started/create-asgardeo-account.md (1)
12-12: Unverified image reference — confirm asset exists before merging.
sign-up-to-asgardeo.pngis a new image added in this PR. As per the existing flagged concern, please confirm the asset is committed to the repository and accessible before merging. As per coding guidelines, "do not reference an image unless the user explicitly confirms it exists and is accessible."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` at line 12, Confirm that the referenced image sign-up-to-asgardeo.png is actually committed to the repo under the assets/img/get-started directory and is reachable via the {{base_path}} variable; if it is missing, add the image file to that assets location (or update the path if it lives elsewhere), then verify the markdown line containing the image reference uses the correct filename and path and that the image renders correctly (run a local docs build or asset-checker) before merging.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 10: Change the sentence "You will receive an email with instructions to
complete your account creation." to present tense and active voice; for example,
replace it with "You receive an email with instructions to complete your account
creation." Update the line in create-asgardeo-account.md where the registration
step is described so the instruction uses present tense consistently.
- Line 34: Update the step text that currently reads "Select **Set a password
for the user** and enter a temporary password. The user can change the password
later." to address the reader directly; change it to something like "Select
**Set a password for the user** and enter a temporary password. You can change
the password later." so the second sentence uses "you" instead of "the user" to
match the tone of the rest of the document.
---
Duplicate comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 12: Confirm that the referenced image sign-up-to-asgardeo.png is actually
committed to the repo under the assets/img/get-started directory and is
reachable via the {{base_path}} variable; if it is missing, add the image file
to that assets location (or update the path if it lives elsewhere), then verify
the markdown line containing the image reference uses the correct filename and
path and that the image renders correctly (run a local docs build or
asset-checker) before merging.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
en/asgardeo/docs/get-started/create-asgardeo-account.md (3)
12-12:⚠️ Potential issue | 🟠 MajorUnverified image reference still present.
The inline image
sign-up-to-asgardeo.pngwas flagged in a prior review as potentially inaccessible. The asset's existence has not been confirmed, and the guideline prohibits referencing images unless explicitly verified. As per coding guidelines, "Do not add, generate, or request new images or screenshots; do not reference an image unless the user explicitly confirms it exists and is accessible."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` at line 12, Remove the unverified inline image reference `sign-up-to-asgardeo.png` from the markdown (the line containing ...) and either replace it with a verified, confirmed asset path provided by the requester or add a placeholder text/alt-only description until the asset is explicitly confirmed; ensure the change is made where that image tag appears so no unverified image references remain in create-asgardeo-account.md.
19-22:⚠️ Potential issue | 🟡 MinorTip body text (line 20) still not indented — renders outside the tip box.
The descriptive sentence at line 20 has zero leading spaces, while
https://console.asgardeo.io/at line 22 is correctly indented 4 spaces. The paragraph therefore renders as plain text before the tip, leaving only the URL inside it. This was previously flagged and marked resolved but persists in the current code.🛠️ Proposed fix
!!! tip "Access the Asgardeo Console" -As an organization owner or administrator, you can manage all organizations, applications, and users you create using the **Asgardeo Console**. Access the console using the following link: + As an organization owner or administrator, you can manage all organizations, applications, and users you create using the **Asgardeo Console**. Access the console using the following link: `https://console.asgardeo.io/`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` around lines 19 - 22, The tip block titled "Access the Asgardeo Console" has its descriptive sentence not indented, so it renders outside the admonition; fix by adding the same 4-space indentation used for the URL to the descriptive sentence so both the sentence and `https://console.asgardeo.io/` are inside the tip block (i.e., indent the line containing "As an organization owner or administrator, you can manage..." to match the URL).
16-17:⚠️ Potential issue | 🟡 MinorAdmonition content still not indented within the note.
The
!!! noteat line 16 is indented 3 spaces (for list nesting); its body at line 17 is also at 3 spaces. The content must be at 7 spaces (3 + 4) to render inside the box. This was previously flagged and marked resolved, but the current code still shows the issue.🛠️ Proposed fix
!!! note - You can also sign in using a social sign-in method to create your account. + You can also sign in using a social sign-in method to create your account.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` around lines 16 - 17, The admonition marker `!!! note` and its body are mis-indented; update the body line containing "You can also sign in using a social sign-in method to create your account." so it is indented four additional spaces relative to the `!!! note` line (total 7 spaces) so the content renders inside the note box; locate the `!!! note` marker and its following body in the create-asgardeo-account.md and increase the body line indentation accordingly.
🧹 Nitpick comments (1)
en/asgardeo/docs/get-started/create-asgardeo-account.md (1)
44-47: Use a bulleted list for non-sequential "What's next?" options.Items 1 and 2 are independent paths the reader can take in any order (or choose only one). Numbered lists imply a required sequence. As per coding guidelines, "Use numbered lists for procedures and ordered steps; use bulleted lists for non-sequential information."
♻️ Proposed fix
Now that you have set up your organization and created your first user, you can: -1. Use a test application to quickly try out Asgardeo. See [Try sign-in with Asgardeo]({{base_path}}/get-started/try-it-application/). -2. Set up Asgardeo in your application or a sample application. See [Start integrating Asgardeo into applications]({{base_path}}/get-started/start-integrating-apps/). +- Use a test application to quickly try out Asgardeo. See [Try sign-in with Asgardeo]({{base_path}}/get-started/try-it-application/). +- Set up Asgardeo in your application or a sample application. See [Start integrating Asgardeo into applications]({{base_path}}/get-started/start-integrating-apps/).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` around lines 44 - 47, Replace the numbered list of "What's next?" options with a bulleted list since the two items ("Try sign-in with Asgardeo" and "Start integrating Asgardeo into applications") are independent; edit the lines containing those two links in create-asgardeo-account.md to change the "1." and "2." list markers to "-" (or "*"), preserving the link targets {{base_path}}/get-started/try-it-application/ and {{base_path}}/get-started/start-integrating-apps/ and their text.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 34: Fix the duplicated list numbering by replacing the leading "4. 4."
with a single "4." on the markdown line that reads "Select **Set a password for
the user**…" so the rendered step number is correct; locate the line containing
the duplicated "4. 4." and edit it to start with "4." only.
- Around line 39-40: The note's body is not indented so it renders outside the
admonition; update the block starting with the "!!! note" marker so that the
following content line(s) are indented by four spaces (i.e., indent the "You can
also manage your account..." line) so they live inside the admonition; ensure
any additional lines under the "!!! note" follow the same 4-space indentation.
---
Duplicate comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 12: Remove the unverified inline image reference
`sign-up-to-asgardeo.png` from the markdown (the line containing ...) and
either replace it with a verified, confirmed asset path provided by the
requester or add a placeholder text/alt-only description until the asset is
explicitly confirmed; ensure the change is made where that image tag appears so
no unverified image references remain in create-asgardeo-account.md.
- Around line 19-22: The tip block titled "Access the Asgardeo Console" has its
descriptive sentence not indented, so it renders outside the admonition; fix by
adding the same 4-space indentation used for the URL to the descriptive sentence
so both the sentence and `https://console.asgardeo.io/` are inside the tip block
(i.e., indent the line containing "As an organization owner or administrator,
you can manage..." to match the URL).
- Around line 16-17: The admonition marker `!!! note` and its body are
mis-indented; update the body line containing "You can also sign in using a
social sign-in method to create your account." so it is indented four additional
spaces relative to the `!!! note` line (total 7 spaces) so the content renders
inside the note box; locate the `!!! note` marker and its following body in the
create-asgardeo-account.md and increase the body line indentation accordingly.
---
Nitpick comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Around line 44-47: Replace the numbered list of "What's next?" options with a
bulleted list since the two items ("Try sign-in with Asgardeo" and "Start
integrating Asgardeo into applications") are independent; edit the lines
containing those two links in create-asgardeo-account.md to change the "1." and
"2." list markers to "-" (or "*"), preserving the link targets
{{base_path}}/get-started/try-it-application/ and
{{base_path}}/get-started/start-integrating-apps/ and their text.
KethniiImasha
force-pushed
the
fix-asgardeo-formatting
branch
from
09415e8 to
4e6c572
Compare
Author
|
Hi @chamilaadhi and the Identity Server docs team, I have addressed all feedback, updated 'login' to 'sign-in', applied active voice, and fixed indentation on note/tip blocks. All checks are passing. I am applying for the WSO2 Engineering Internship and would appreciate a review when you have a moment. Thank you. |
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
KethniiImasha
force-pushed
the
fix-asgardeo-formatting
branch
from
4e6c572 to
ab79ae1
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
en/asgardeo/docs/get-started/create-asgardeo-account.md (1)
7-7: Consider replacing the "is" verb for stronger phrasing.The definition uses "is", which is a weak be verb. While definitions often require "is", you can rephrase for more direct language.
✏️ Alternative phrasing
-An organization in Asgardeo is your own unique space that contains your users and application configurations. Sign up to create your first organization. +An organization in Asgardeo provides a unique space for your users and application configurations. Sign up to create your first organization.As per coding guidelines, "Reduce unnecessary use of weak 'be' verbs (am, is, are, was, were) and prefer direct verbs."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/get-started/create-asgardeo-account.md` at line 7, Replace the weak "is" construction in the sentence "An organization in Asgardeo is your own unique space that contains your users and application configurations. Sign up to create your first organization." with a stronger, active verb; for example, update the sentence to "An Asgardeo organization gives you a unique space for your users and application configurations. Sign up to create your first organization." and apply this change where that sentence appears in create-asgardeo-account.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@en/asgardeo/docs/get-started/create-asgardeo-account.md`:
- Line 7: Replace the weak "is" construction in the sentence "An organization in
Asgardeo is your own unique space that contains your users and application
configurations. Sign up to create your first organization." with a stronger,
active verb; for example, update the sentence to "An Asgardeo organization gives
you a unique space for your users and application configurations. Sign up to
create your first organization." and apply this change where that sentence
appears in create-asgardeo-account.md.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/asgardeo/docs/get-started/create-asgardeo-account.mden/asgardeo/docs/get-started/index.md
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
The goal of this PR is to improve the readability and consistency of the Asgardeo Get Started documentation. The following enhancements were made:
Active Voice: Refined introductory text to use the active voice, making the guides more direct and reader-focused.
Formatting Consistency: Standardized the bolding of UI elements, specifically for the Asgardeo Console and the Asgardeo self-service portal, to align with the WSO2 Style Guide.
Fixing Errors: Corrected a numbering discrepancy in the "Create a user" section of the onboarding guide.
Related PRs
N/A
Test environment
OS: macOS (Apples-MacBook-Air)
Editor: Visual Studio Code
Testing: Verified Markdown rendering using VS Code's built-in preview tool to ensure all links and bolding appear correctly.
Security checks
Summary by CodeRabbit