From d66569b6480e9ec74e689eef44138997c5816821 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 30 Jan 2026 19:07:18 +0530
Subject: [PATCH 01/10] docs: migrate issue tracking to GitHub Issues and
 Discussions

---
 src/site/content/support.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/site/content/support.adoc b/src/site/content/support.adoc
index 2bdedcc2a..9a4968a14 100644
--- a/src/site/content/support.adoc
+++ b/src/site/content/support.adoc
@@ -10,8 +10,9 @@ The Shiro project offers support through its community of users, contributors, a
 
 We encourage everyone to participate and use the available community support tools below.
 
+* https://github.com/apache/shiro/discussions[GitHub Discussions] - For questions, ideas, and community discussion
+* https://github.com/apache/shiro/issues[GitHub Issues] - For bug reports and feature requests
 * link:troubleshooting.html[Troubleshooting & FAQ]
 * link:mailing-lists.html[Mailing Lists]
 * link:forums.html[Forums]
-* link:issues.html[Issues and Bug Tracking]
 * link:commercial-support.html[Commercial Support]

From 36dc354a6f476be7b09d4cbd85e596d815c5ae05 Mon Sep 17 00:00:00 2001
From: lprimak <lenny@flowlogix.com>
Date: Fri, 30 Jan 2026 11:44:25 -0600
Subject: [PATCH 02/10] review comments

---
 src/site/content/support.adoc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/site/content/support.adoc b/src/site/content/support.adoc
index 9a4968a14..2bdedcc2a 100644
--- a/src/site/content/support.adoc
+++ b/src/site/content/support.adoc
@@ -10,9 +10,8 @@ The Shiro project offers support through its community of users, contributors, a
 
 We encourage everyone to participate and use the available community support tools below.
 
-* https://github.com/apache/shiro/discussions[GitHub Discussions] - For questions, ideas, and community discussion
-* https://github.com/apache/shiro/issues[GitHub Issues] - For bug reports and feature requests
 * link:troubleshooting.html[Troubleshooting & FAQ]
 * link:mailing-lists.html[Mailing Lists]
 * link:forums.html[Forums]
+* link:issues.html[Issues and Bug Tracking]
 * link:commercial-support.html[Commercial Support]

From 0d145efd6d4334c3756e3fed7e097906daeb6987 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Sat, 31 Jan 2026 11:55:19 +0530
Subject: [PATCH 03/10] docs: address PR review feedback

---
 src/site/content/community.adoc | 6 ++----
 src/site/content/forums.adoc    | 6 +-----
 src/site/content/issues.adoc    | 4 ++--
 3 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/src/site/content/community.adoc b/src/site/content/community.adoc
index e71a446f9..368a7ebaf 100644
--- a/src/site/content/community.adoc
+++ b/src/site/content/community.adoc
@@ -10,9 +10,9 @@ We have a great user and developer community and hope that you become an active
 
 Our community is here to help you learn about Shiro, figure out how to do what you need, identify and fix any bugs, and improve Shiro so that it continues to be a powerful and useful software project.
 
-* *link:forums.html[Community Forums]* - Need help? For users that prefer to use forums over mailing lists, we use Nabble
+* *https://github.com/apache/shiro/discussions[GitHub Discussions]* - Need help? Ask questions and discuss ideas with the community
 
-* *link:mailing-lists.html[Mailing Lists]* - Need help, but hate forums? Lists for Users, Developers and Committers!
+* *link:mailing-lists.html[Mailing Lists]* - Lists for Users, Developers and Committers!
 
 * *link:articles.html[Articles]* - Read up on the latest discussions, guides, and how-tos created by members of our community
 
@@ -30,8 +30,6 @@ At the Shiro project we make it easy for anyone to join our great community and
 
 * *link:developer-resources.html[Developer Resources]* - Helpful information for anyone providing project help as a committer or contributor
 
-* *https://github.com/apache/shiro/discussions[GitHub Discussions]* - For questions, ideas, and community discussion
-
 * *https://github.com/apache/shiro/issues[GitHub Issues]* - For bug reports and feature requests
 
 * *https://www.apache.org/foundation/sponsorship.html[Donate to ASF]* - Shiro is a project under the Apache Software Foundation, a non-profit that relies on donations and community support
diff --git a/src/site/content/forums.adoc b/src/site/content/forums.adoc
index 2dc919c6b..64a129672 100644
--- a/src/site/content/forums.adoc
+++ b/src/site/content/forums.adoc
@@ -23,11 +23,7 @@ For users that prefer to browse the mailing lists with a browser can use https:/
 
 * link:++https://lists.apache.org/list.html?dev@shiro.apache.org++[Shiro Developer Forum]
 
-____
-
-*NOTE:* Previously, `nabble.com` was used as an alternative to the mailing list, this service is no longer hosting the mailing list archive.
-
-____
+NOTE: Previously, `nabble.com` was used as an alternative to the mailing list, this service is no longer hosting the mailing list archive.
 
 == GitHub Discussions
 
diff --git a/src/site/content/issues.adoc b/src/site/content/issues.adoc
index 79904b4a9..994160f5f 100644
--- a/src/site/content/issues.adoc
+++ b/src/site/content/issues.adoc
@@ -2,8 +2,8 @@
 :jbake-date: 2010-03-18 00:00:00
 :jbake-type: page
 :jbake-status: published
-:jbake-tags: issues, bugs, jira, bug-tracking, support
-:jbake-description: Report bugs, request features, and track issues for Apache Shiro using GitHub Issues tracking system.
+:jbake-tags: issues, bugs, bug-tracking, support
+:jbake-description: Report bugs, request features, and track issues for Apache Shiro using GitHub Issues.
 :idprefix:
 :icons: font
 

From ffe84565217787729aa2421500b38764ec338cd3 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:10:44 +0530
Subject: [PATCH 04/10] docs: complete authenticator and authorizer
 documentation

---
 src/site/content/authenticator.adoc | 110 ++++++++++++++++++++++-
 src/site/content/authorizer.adoc    | 134 +++++++++++++++++++++++++++-
 2 files changed, 236 insertions(+), 8 deletions(-)

diff --git a/src/site/content/authenticator.adoc b/src/site/content/authenticator.adoc
index 5cb29fd43..f29c0d379 100644
--- a/src/site/content/authenticator.adoc
+++ b/src/site/content/authenticator.adoc
@@ -1,8 +1,110 @@
-= Authenticator
-:jbake-type: lend_a_hand
+[#Authenticator-UnderstandingAuthenticators]
+= Apache Shiro Authenticators
+:jbake-date: 2010-03-18 00:00:00
+:jbake-type: page
 :jbake-status: published
-:jbake-tags: documentation, todo, lend-a-hand
+:jbake-tags: authenticator, authentication, security, realms
+:jbake-description: Understanding Apache Shiro Authenticators - the component responsible for verifying user identity. Learn how Authenticators work with Realms and AuthenticationStrategies.
 :idprefix:
 :icons: font
+:toc:
 
-TODO
+An `Authenticator` is a component responsible for verifying that a user actually is who they claim to be.
+It is the core component that executes the authentication process on behalf of the link:/subject.html[Subject].
+
+While the link:/authentication.html[Authentication] documentation explains the concepts and workflow of authentication in Shiro,
+the Authenticator represents the actual implementation component that performs identity verification.
+
+[#Authenticator-Role]
+== Role in the SecurityManager
+
+The link:/securitymanager.html[SecurityManager] does not perform authentication directly.
+Instead, it delegates authentication requests to its internal `Authenticator` instance.
+When a link:/subject.html[Subject] calls link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)[`login(token)`],
+the SecurityManager receives the request and immediately delegates to the Authenticator by calling
+link:/static/current/apidocs/org/apache/shiro/authc/Authenticator.html#authenticate(org.apache.shiro.authc.AuthenticationToken)[`authenticate(token)`].
+
+The Authenticator takes the submitted link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html[`AuthenticationToken`] 
+and uses it to verify the Subject's identity.
+If verification succeeds, it returns an link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html[`AuthenticationInfo`] object.
+If verification fails, it throws an link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthenticationException`].
+
+[#Authenticator-ModularRealmAuthenticator]
+== ModularRealmAuthenticator
+
+Shiro uses the link:/static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html[`ModularRealmAuthenticator`] 
+by default.
+This implementation supports coordinating one or more link:/realm.html[Realms] during the authentication process.
+
+When an authentication token is submitted, the ModularRealmAuthenticator:
+
+* Iterates through configured Realms
+* Calls each Realm's link:/static/current/apidocs/org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)[`supports(token)`] method to determine if the Realm can process the token
+* If a Realm supports the token, its link:/static/current/apidocs/org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)[`getAuthenticationInfo(token)`] method is invoked
+* Returns authentication information if successful, or throws an exception if failed
+
+[#Authenticator-SingleVsMultipleRealms]
+== Single vs. Multiple Realms
+
+The ModularRealmAuthenticator supports both configurations:
+
+*Single Realm*:
+When only one Realm is configured, the Authenticator directly invokes that Realm to verify the Subject's credentials.
+
+*Multiple Realms*:
+When multiple Realms are configured, the Authenticator uses an link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[`AuthenticationStrategy`]
+to determine how to coordinate authentication across the Realms.
+This is a link:https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[PAM]-style approach where each Realm can be consulted in sequence.
+
+[#Authenticator-AuthenticationStrategy]
+== AuthenticationStrategy
+
+When multiple Realms are configured, the Authenticator must determine if the overall authentication attempt succeeds or fails.
+The link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[`AuthenticationStrategy`] makes this determination.
+
+Shiro provides three built-in strategies:
+
+* *FirstSuccessfulStrategy*: Returns the first Realm that succeeds. Other Realms are not consulted.
+* *AtLeastOneSuccessfulStrategy*: Returns success if at least one Realm succeeds. Other Realms continue to be consulted.
+* *AllSuccessfulStrategy*: All Realms must succeed for authentication to succeed. This is the most restrictive.
+
+You can configure which strategy the Authenticator uses, or implement your own strategy for custom behavior.
+
+[#Authenticator-Configuration]
+== Configuration
+
+You can configure a custom Authenticator in your Shiro configuration if needed:
+
+[source,ini]
+----
+authenticator = com.foo.bar.CustomAuthenticator
+securityManager.authenticator = $authenticator
+----
+
+You can also configure the AuthenticationStrategy:
+
+[source,ini]
+----
+authenticationStrategy = org.apache.shiro.authc.pam.FirstSuccessfulStrategy
+authenticator.authenticationStrategy = $authenticationStrategy
+----
+
+However, in most cases, the default ModularRealmAuthenticator with the default strategy is sufficient for typical applications.
+
+[#Authenticator-RealmInteraction]
+== How Authenticators Work with Realms
+
+The Authenticator does not directly know how to verify credentials.
+Instead, it coordinates with configured Realms to perform the actual verification.
+
+A link:/realm.html[Realm] is a security-specific data access object that can locate and validate user credentials from a data source
+(database, LDAP, file system, etc.).
+The Realm is responsible for:
+
+* Determining if it understands the submitted AuthenticationToken via its `supports(token)` method
+* Looking up the user in the data source
+* Comparing submitted credentials with those stored in the data source
+* Returning the user's authentication information if credentials match
+* Throwing an exception if credentials do not match
+
+The Authenticator simply orchestrates this process by delegating to Realms in order and handling the results according to its configured strategy.
diff --git a/src/site/content/authorizer.adoc b/src/site/content/authorizer.adoc
index 7b9ca4a8f..076aabd89 100644
--- a/src/site/content/authorizer.adoc
+++ b/src/site/content/authorizer.adoc
@@ -1,8 +1,134 @@
-= Authorizer
-:jbake-type: lend_a_hand
+[#Authorizer-UnderstandingAuthorizers]
+= Apache Shiro Authorizers
+:jbake-date: 2010-03-18 00:00:00
+:jbake-type: page
 :jbake-status: published
-:jbake-tags: documentation, todo, lend-a-hand
+:jbake-tags: authorizer, authorization, access-control, permissions, roles
+:jbake-description: Understanding Apache Shiro Authorizers - the component that determines what authenticated users are allowed to do. Learn how Authorizers work with Realms to evaluate permissions and roles.
 :idprefix:
 :icons: font
+:toc:
 
-TODO
+An `Authorizer` is a component responsible for determining whether a user is allowed to perform a certain action.
+It evaluates whether a `Subject` has the necessary permissions or roles to access a resource or perform an operation.
+
+While the link:/authorization.html[Authorization] documentation explains the concepts and workflow of access control in Shiro,
+the Authorizer represents the actual implementation component that performs access control decisions.
+
+[#Authorizer-Role]
+== Role in the SecurityManager
+
+The link:/securitymanager.html[SecurityManager] does not perform authorization checks directly.
+Instead, it delegates authorization decisions to its internal `Authorizer` instance.
+When a link:/subject.html[Subject] calls authorization methods such as
+link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`hasRole(role)`],
+link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)[`isPermitted(permission)`],
+or their variants, the SecurityManager delegates to the Authorizer.
+
+The Authorizer determines whether the Subject is permitted to perform the requested action by checking the Subject's roles and permissions.
+If the Subject has the necessary role or permission, the authorization check passes.
+If not, an link:/static/current/apidocs/org/apache/shiro/authz/AuthorizationException.html[`AuthorizationException`] may be thrown.
+
+[#Authorizer-ModularRealmAuthorizer]
+== ModularRealmAuthorizer
+
+Shiro uses the link:/static/current/apidocs/org/apache/shiro/authz/ModularRealmAuthorizer.html[`ModularRealmAuthorizer`] 
+by default.
+This implementation supports coordinating one or more link:/realm.html[Realms] during the authorization process.
+
+When an authorization check is performed, the ModularRealmAuthorizer:
+
+* Iterates through configured Realms
+* For each Realm that implements the `Authorizer` interface, calls the corresponding authorization method
+  (`hasRole*`, `checkRole*`, `isPermitted*`, or `checkPermission*`)
+* Aggregates and evaluates the results according to Shiro's authorization semantics
+* Returns the authorization decision to the caller
+
+It is important to note that the ModularRealmAuthorizer treats Realms differently depending on whether they implement the `Authorizer` interface.
+If a Realm does not implement `Authorizer`, it is not consulted for authorization checks.
+
+[#Authorizer-PermissionAndRoleChecks]
+== Permission and Role Checks
+
+The Authorizer performs two types of authorization checks:
+
+[#Authorizer-PermissionChecks]
+=== Permission Checks
+
+Permission checks verify whether a Subject is allowed to perform a specific action on a specific resource.
+Methods for permission checks include:
+
+* link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(org.apache.shiro.authz.Permission)[`isPermitted(permission)`] - returns `true` or `false`
+* link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#checkPermission(org.apache.shiro.authz.Permission)[`checkPermission(permission)`] - throws an exception on failure
+
+For example:
+
+[source,java]
+----
+if (subject.isPermitted("account:read")) {
+    //User can read accounts
+}
+
+subject.checkPermission("document:delete:report123");
+----
+
+[#Authorizer-RoleChecks]
+=== Role Checks
+
+Role checks verify whether a Subject has a specific role. Methods for role checks include:
+
+* link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)[`hasRole(role)`] - returns `true` or `false`
+* link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#checkRole(java.lang.String)[`checkRole(role)`] - throws an exception on failure
+
+For example:
+
+[source,java]
+----
+if (subject.hasRole("admin")) {
+    //User is an administrator
+}
+
+subject.checkRole("user");
+----
+
+[#Authorizer-Configuration]
+== Configuration
+
+You can configure a custom Authorizer in your Shiro configuration if needed:
+
+[source,ini]
+----
+authorizer = com.foo.bar.CustomAuthorizer
+securityManager.authorizer = $authorizer
+----
+
+However, in most cases, the default ModularRealmAuthorizer is sufficient for typical applications.
+
+[#Authorizer-RealmInteraction]
+== How Authorizers Work with Realms
+
+The Authorizer does not directly know where to retrieve authorization data.
+Instead, it coordinates with configured Realms to perform the actual authorization checks.
+
+A link:/realm.html[Realm] is a security-specific data access object that knows how to retrieve authorization data from a data source
+(database, LDAP, file system, etc.).
+The Realm is responsible for:
+
+* Determining if it implements the `Authorizer` interface (which indicates it can perform authorization checks)
+* Retrieving the Subject's roles and permissions from the data source
+* Evaluating whether the Subject has the requested role or permission
+* Returning the results of the authorization check
+
+The Authorizer simply orchestrates this process by delegating to Realms and aggregating their results.
+This allows you to use multiple Realms where authorization data may come from different sources,
+and Shiro will coordinate the results appropriately.
+
+[#Authorizer-MultipleRealms]
+== Authorization with Multiple Realms
+
+When multiple Realms are configured, the ModularRealmAuthorizer consults all Realms that implement the `Authorizer` interface.
+The results are aggregated to determine the final authorization decision.
+
+Typically, if any Realm grants permission or role membership, the authorization check succeeds.
+However, the exact behavior depends on the authorization data model and how the Realms are configured.
+Custom Authorizer implementations can be used to implement different aggregation strategies if needed.

From 818b1541135297ba73f3589184c2647b43a29d7a Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:17:35 +0530
Subject: [PATCH 05/10] merge: resolve conflicts by accepting latest changes
 from main

- community.adoc: Update to use GitHub Discussions instead of Nabble
- forums.adoc: Restructure and add GitHub Discussions section
- issues.adoc: Update from Jira to GitHub Issues for issue tracking
---
 src/site/content/community.adoc |  9 ++++-----
 src/site/content/forums.adoc    | 25 ++++++++-----------------
 src/site/content/issues.adoc    | 25 ++++++++-----------------
 3 files changed, 20 insertions(+), 39 deletions(-)

diff --git a/src/site/content/community.adoc b/src/site/content/community.adoc
index 368a7ebaf..06558e002 100644
--- a/src/site/content/community.adoc
+++ b/src/site/content/community.adoc
@@ -2,17 +2,16 @@
 :jbake-date: 2010-03-18 00:00:00
 :jbake-type: page
 :jbake-status: published
-:jbake-tags: community, support, forums, mailing-lists
-:jbake-description: Join the Apache Shiro community to get help, share knowledge, and contribute. Access forums, mailing lists, articles, and community events.
+:jbake-tags: community
 :idprefix:
 
 We have a great user and developer community and hope that you become an active participant.
 
 Our community is here to help you learn about Shiro, figure out how to do what you need, identify and fix any bugs, and improve Shiro so that it continues to be a powerful and useful software project.
 
-* *https://github.com/apache/shiro/discussions[GitHub Discussions]* - Need help? Ask questions and discuss ideas with the community
+* *link:forums.html[Community Forums]* - Need help? For users that prefer to use forums over mailing lists, we use Nabble
 
-* *link:mailing-lists.html[Mailing Lists]* - Lists for Users, Developers and Committers!
+* *link:mailing-lists.html[Mailing Lists]* - Need help, but hate forums? Lists for Users, Developers and Committers!
 
 * *link:articles.html[Articles]* - Read up on the latest discussions, guides, and how-tos created by members of our community
 
@@ -30,6 +29,6 @@ At the Shiro project we make it easy for anyone to join our great community and
 
 * *link:developer-resources.html[Developer Resources]* - Helpful information for anyone providing project help as a committer or contributor
 
-* *https://github.com/apache/shiro/issues[GitHub Issues]* - For bug reports and feature requests
+* *https://github.com/apache/shiro/issues[Issue Tracker]* - Once you're ready to contribute, this is a good place to see what needs to get done
 
 * *https://www.apache.org/foundation/sponsorship.html[Donate to ASF]* - Shiro is a project under the Apache Software Foundation, a non-profit that relies on donations and community support
diff --git a/src/site/content/forums.adoc b/src/site/content/forums.adoc
index 64a129672..6202f54f1 100644
--- a/src/site/content/forums.adoc
+++ b/src/site/content/forums.adoc
@@ -2,30 +2,21 @@
 :jbake-date: 2010-03-18 00:00:00
 :jbake-type: page
 :jbake-status: published
-:jbake-tags: forums, community, support, discussions
-:jbake-description: Access Apache Shiro community forums and mailing list archives via ASF Pony Mail for user and developer discussions.
+:jbake-tags: documentation, community
 :idprefix:
 
-== Mailing Lists
-
-For those that may prefer mailing lists, please see the link:mailing-lists.html[Mailing Lists] information.
-____
-
-*NOTE:* The primary forums for Apache Shiro are the mailing lists, which can be accessed via the link:mailing-lists.html[Mailing Lists] page. This is per the Apache Software Foundation's community guidelines.
-
-____
-
-== Mailing List Archives
-
-For users that prefer to browse the mailing lists with a browser can use https://lists.apache.org/[ASF Lists] (Pony Mail).
+For users that prefer to use browse the mailing lists with a browser can use https://lists.apache.org/[ASF Lists] (Pony Mail).
 
 * link:++https://lists.apache.org/list.html?user@shiro.apache.org++[Shiro User Forum]
 
 * link:++https://lists.apache.org/list.html?dev@shiro.apache.org++[Shiro Developer Forum]
 
-NOTE: Previously, `nabble.com` was used as an alternative to the mailing list, this service is no longer hosting the mailing list archive.
+____
+
+*NOTE:* Previously, `nabble.com` was used as an alternative to the mailing list, this service is no longer hosting the mailing list archive.
 
-== GitHub Discussions
+____
 
-For questions, ideas, and general community discussion, please use https://github.com/apache/shiro/discussions[GitHub Discussions].
+== Mailing Lists
 
+For those that may prefer mailing lists, please see the link:mailing-lists.html[Mailing Lists] information.
\ No newline at end of file
diff --git a/src/site/content/issues.adoc b/src/site/content/issues.adoc
index 994160f5f..a7f0918cd 100644
--- a/src/site/content/issues.adoc
+++ b/src/site/content/issues.adoc
@@ -2,33 +2,24 @@
 :jbake-date: 2010-03-18 00:00:00
 :jbake-type: page
 :jbake-status: published
-:jbake-tags: issues, bugs, bug-tracking, support
-:jbake-description: Report bugs, request features, and track issues for Apache Shiro using GitHub Issues.
+:jbake-tags: documentation, support, community, issues, bugs
 :idprefix:
 :icons: font
 
-Apache Shiro uses https://github.com/apache/shiro/issues[GitHub Issues] for bug reports, feature requests, and task tracking.
-
-For questions, ideas, and community discussions, please use https://github.com/apache/shiro/discussions[GitHub Discussions].
+Apache Shiro uses Atlassian Jira for tracking tasks, feature requests, bugs, and other issues related to the project development.
 
 == Usage Guidelines
 
-GitHub Issues is provided as a Shiro software development resource.
-It is meant for reporting bugs, requesting features, and tracking improvements in the software itself - it is not a support portal to ask for advice or help.
-For community advice and help in using Apache Shiro, please visit the link:/support.html[Support] page or use https://github.com/apache/shiro/discussions[GitHub Discussions].
+Jira is provided as a Shiro software development resource.
+It is meant to be for managing bugs, tasks and improvements in the software itself - it is not a support portal to ask for advice or help.
+For community advice and help in using Apache Shiro, please visit the link:/support.html[Support] page.
 
-*Prior to opening an issue, we ask that:*
+*Prior to using Jira, we ask that:*
 
 * You do your due diligence to ensure a suspected error is actually a bug.
 * You search the issue tracker to ensure what you want to report has not already been reported by someone else.
 * If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem, so we can fix it as fast as possible.
 * If a unit test is not available (please really try to make one!), attach a stack trace and Shiro's TRACE or DEBUG log output.
-* If you've already fixed the problem, please submit a pull request, and we'll likely include it in the next release.
-
-https://github.com/apache/shiro/issues[Click here to visit the Apache Shiro GitHub Issues tracker].
-
-== JIRA (Legacy)
-
-JIRA is retained for archival purposes only and is no longer used for new issues.
+* If you've already fixed the problem, please submit a patch, and we'll likely include it in the next release.
 
-https://issues.apache.org/jira/browse/SHIRO[Click here to visit the legacy Apache Shiro JIRA issue tracker].
+https://issues.apache.org/jira/browse/SHIRO[Click here to visit the Apache Shiro Jira issue tracker].

From c91157689ae9227d54349ccaa85c6ba695ac3e40 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:19:12 +0530
Subject: [PATCH 06/10] fix: update issues.adoc to use GitHub Issues instead of
 Jira

---
 src/site/content/issues.adoc | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/src/site/content/issues.adoc b/src/site/content/issues.adoc
index a7f0918cd..994160f5f 100644
--- a/src/site/content/issues.adoc
+++ b/src/site/content/issues.adoc
@@ -2,24 +2,33 @@
 :jbake-date: 2010-03-18 00:00:00
 :jbake-type: page
 :jbake-status: published
-:jbake-tags: documentation, support, community, issues, bugs
+:jbake-tags: issues, bugs, bug-tracking, support
+:jbake-description: Report bugs, request features, and track issues for Apache Shiro using GitHub Issues.
 :idprefix:
 :icons: font
 
-Apache Shiro uses Atlassian Jira for tracking tasks, feature requests, bugs, and other issues related to the project development.
+Apache Shiro uses https://github.com/apache/shiro/issues[GitHub Issues] for bug reports, feature requests, and task tracking.
+
+For questions, ideas, and community discussions, please use https://github.com/apache/shiro/discussions[GitHub Discussions].
 
 == Usage Guidelines
 
-Jira is provided as a Shiro software development resource.
-It is meant to be for managing bugs, tasks and improvements in the software itself - it is not a support portal to ask for advice or help.
-For community advice and help in using Apache Shiro, please visit the link:/support.html[Support] page.
+GitHub Issues is provided as a Shiro software development resource.
+It is meant for reporting bugs, requesting features, and tracking improvements in the software itself - it is not a support portal to ask for advice or help.
+For community advice and help in using Apache Shiro, please visit the link:/support.html[Support] page or use https://github.com/apache/shiro/discussions[GitHub Discussions].
 
-*Prior to using Jira, we ask that:*
+*Prior to opening an issue, we ask that:*
 
 * You do your due diligence to ensure a suspected error is actually a bug.
 * You search the issue tracker to ensure what you want to report has not already been reported by someone else.
 * If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem, so we can fix it as fast as possible.
 * If a unit test is not available (please really try to make one!), attach a stack trace and Shiro's TRACE or DEBUG log output.
-* If you've already fixed the problem, please submit a patch, and we'll likely include it in the next release.
+* If you've already fixed the problem, please submit a pull request, and we'll likely include it in the next release.
+
+https://github.com/apache/shiro/issues[Click here to visit the Apache Shiro GitHub Issues tracker].
+
+== JIRA (Legacy)
+
+JIRA is retained for archival purposes only and is no longer used for new issues.
 
-https://issues.apache.org/jira/browse/SHIRO[Click here to visit the Apache Shiro Jira issue tracker].
+https://issues.apache.org/jira/browse/SHIRO[Click here to visit the legacy Apache Shiro JIRA issue tracker].

From 76294ef46c5dbcda1af7068cae7578442e7a7db3 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:36:11 +0530
Subject: [PATCH 07/10] docs: clarify FirstSuccessfulStrategy description for
 better clarity

---
 src/site/content/authenticator.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/site/content/authenticator.adoc b/src/site/content/authenticator.adoc
index f29c0d379..327c40abe 100644
--- a/src/site/content/authenticator.adoc
+++ b/src/site/content/authenticator.adoc
@@ -64,7 +64,7 @@ The link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrate
 
 Shiro provides three built-in strategies:
 
-* *FirstSuccessfulStrategy*: Returns the first Realm that succeeds. Other Realms are not consulted.
+* *FirstSuccessfulStrategy*: Consults Realms in order until one succeeds. Remaining Realms are not consulted.
 * *AtLeastOneSuccessfulStrategy*: Returns success if at least one Realm succeeds. Other Realms continue to be consulted.
 * *AllSuccessfulStrategy*: All Realms must succeed for authentication to succeed. This is the most restrictive.
 

From 22d2163f10752dd8927048cdf322cf460eab1dbe Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:49:40 +0530
Subject: [PATCH 08/10] build: improve shiro-site build performance

Optimize the Validator to use buffered file reading with early exit
instead of reading entire files into memory. JBake metadata headers
are always at the top of .adoc files, so we only need to read the
first few lines to validate them.

Changes:
- Use BufferedReader instead of Files.readAllLines()
- Exit early when validation passes (date found or redirect page)
- Limit reading to first 50 lines (headers are typically in first 10)

This reduces memory usage and improves validation speed for large files.
---
 .../java/org/apache/shiro/site/Validator.java | 51 +++++++++++++------
 1 file changed, 35 insertions(+), 16 deletions(-)

diff --git a/src/main/java/org/apache/shiro/site/Validator.java b/src/main/java/org/apache/shiro/site/Validator.java
index 72f5c23d4..55aedfabd 100644
--- a/src/main/java/org/apache/shiro/site/Validator.java
+++ b/src/main/java/org/apache/shiro/site/Validator.java
@@ -18,6 +18,7 @@
  */
 package org.apache.shiro.site;
 
+import java.io.BufferedReader;
 import java.io.IOException;
 import java.nio.file.FileVisitResult;
 import java.nio.file.Files;
@@ -30,6 +31,9 @@
 public final class Validator implements Runnable {
     private final Path content;
 
+    // JBake headers are in the first few lines, no need to read entire files
+    private static final int MAX_HEADER_LINES = 50;
+
     private Validator(final Path content) {
         this.content = content;
     }
@@ -61,25 +65,40 @@ public FileVisitResult visitFile(final Path file, final BasicFileAttributes attr
     }
 
     private void doValidateContent(final Path file, final List<String> errors) throws IOException {
-        final var lines = Files.readAllLines(file); // don't use asciidoctorj to parse properly the adoc, it is way too slow to start
-        if (missDate(lines) &&
-                isNotRedirect(lines) &&
-                isNotTODO(lines)) {
-            errors.add("Missing date in '" + content.relativize(file) + "'");
-        }
-    }
+        // Only read header lines - JBake metadata is always at the top
+        // This avoids reading entire files which can be hundreds of lines
+        try (BufferedReader reader = Files.newBufferedReader(file)) {
+            String line;
+            int lineCount = 0;
+            boolean hasDate = false;
+            boolean isRedirect = false;
+            boolean hasTodo = false;
 
-    // if the page is not written, no big deal to be broken
-    private boolean isNotTODO(final List<String> lines) {
-        return !(lines.size() < 10 && lines.contains("TODO"));
-    }
+            while ((line = reader.readLine()) != null && lineCount < MAX_HEADER_LINES) {
+                lineCount++;
 
-    private boolean isNotRedirect(final List<String> lines) {
-        return lines.stream().noneMatch(":jbake-type: redirect"::equals);
-    }
+                if (line.startsWith(":jbake-date:")) {
+                    hasDate = true;
+                    return; // valid, no need to check further
+                }
+                if (":jbake-type: redirect".equals(line)) {
+                    isRedirect = true;
+                    return; // redirect pages don't need date validation
+                }
+                if ("TODO".equals(line)) {
+                    hasTodo = true;
+                }
+            }
+
+            // If page is a TODO stub (small file with TODO marker), skip validation
+            if (lineCount < 10 && hasTodo) {
+                return;
+            }
 
-    private boolean missDate(final List<String> lines) {
-        return lines.stream().noneMatch(l -> l.startsWith(":jbake-date:"));
+            if (!hasDate && !isRedirect) {
+                errors.add("Missing date in '" + content.relativize(file) + "'");
+            }
+        }
     }
 
     public static void main(final String... args) throws IOException {

From 1e9b77cc318b1515acb2addb8beea37af69364b4 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 09:59:11 +0530
Subject: [PATCH 09/10] docs: improve documentation content structure and
 navigation

---
 src/site/content/authenticator.adoc           | 11 +++++
 src/site/content/authorizer.adoc              | 12 ++++++
 .../2024/11/apache-shiro-202-released.adoc    |  6 +++
 .../2025/07/apache-shiro-205-released.adoc    |  6 +++
 .../2025/11/apache-shiro-206-released.adoc    |  6 +++
 src/site/content/documentation.adoc           | 18 +++++++--
 src/site/content/get-started.adoc             | 16 +++++++-
 src/site/content/guides.adoc                  | 40 ++++++++++++++++---
 .../content/java-authentication-guide.adoc    | 10 +++++
 .../content/java-authorization-guide.adoc     | 12 +++++-
 src/site/content/reference.adoc               | 14 +++++++
 11 files changed, 139 insertions(+), 12 deletions(-)

diff --git a/src/site/content/authenticator.adoc b/src/site/content/authenticator.adoc
index 327c40abe..a56c22586 100644
--- a/src/site/content/authenticator.adoc
+++ b/src/site/content/authenticator.adoc
@@ -108,3 +108,14 @@ The Realm is responsible for:
 * Throwing an exception if credentials do not match
 
 The Authenticator simply orchestrates this process by delegating to Realms in order and handling the results according to its configured strategy.
+
+[#Authenticator-SeeAlso]
+== See Also
+
+To learn more about related topics, see:
+
+* link:authentication.html[Authentication] - Conceptual overview of authentication in Shiro.
+* link:java-authentication-guide.html[Java Authentication Guide] - Practical guide to implementing authentication in your application.
+* link:realm.html[Realms] - How Realms connect Shiro to your data sources.
+* link:authorizer.html[Authorizers] - The counterpart component for authorization.
+* link:securitymanager.html[SecurityManager] - The component that orchestrates Authenticators and other Shiro components.
diff --git a/src/site/content/authorizer.adoc b/src/site/content/authorizer.adoc
index 076aabd89..5d345a6c3 100644
--- a/src/site/content/authorizer.adoc
+++ b/src/site/content/authorizer.adoc
@@ -132,3 +132,15 @@ The results are aggregated to determine the final authorization decision.
 Typically, if any Realm grants permission or role membership, the authorization check succeeds.
 However, the exact behavior depends on the authorization data model and how the Realms are configured.
 Custom Authorizer implementations can be used to implement different aggregation strategies if needed.
+
+[#Authorizer-SeeAlso]
+== See Also
+
+To learn more about related topics, see:
+
+* link:authorization.html[Authorization] - Conceptual overview of authorization in Shiro.
+* link:java-authorization-guide.html[Java Authorization Guide] - Practical guide to implementing authorization in your application.
+* link:permissions.html[Permissions] - Understanding Shiro's permission model.
+* link:realm.html[Realms] - How Realms connect Shiro to your data sources.
+* link:authenticator.html[Authenticators] - The counterpart component for authentication.
+* link:securitymanager.html[SecurityManager] - The component that orchestrates Authorizers and other Shiro components.
diff --git a/src/site/content/blog/2024/11/apache-shiro-202-released.adoc b/src/site/content/blog/2024/11/apache-shiro-202-released.adoc
index 7686f0811..15c925de8 100644
--- a/src/site/content/blog/2024/11/apache-shiro-202-released.adoc
+++ b/src/site/content/blog/2024/11/apache-shiro-202-released.adoc
@@ -44,6 +44,12 @@ You can learn more on link:https://github.com/apache/shiro/releases/tag/shiro-ro
 
 Download and verification instructions are available link:/download.html[on our download page].
 
+== Migration Notes
+
+This is a maintenance release within the 2.x series. If you are already running Shiro 2.x, upgrading to 2.0.2 should be straightforward with no breaking changes expected.
+
+If you are upgrading from Shiro 1.x, please review the link:/migration-guide.html[Migration Guide] for important changes between major versions.
+
 == Documentation
 
 For more information on link:/documentation.html[Shiro, please read the documentation.]
diff --git a/src/site/content/blog/2025/07/apache-shiro-205-released.adoc b/src/site/content/blog/2025/07/apache-shiro-205-released.adoc
index a6c2031a5..905a20e07 100644
--- a/src/site/content/blog/2025/07/apache-shiro-205-released.adoc
+++ b/src/site/content/blog/2025/07/apache-shiro-205-released.adoc
@@ -43,6 +43,12 @@ You can learn more on link:https://github.com/apache/shiro/releases/tag/shiro-ro
 
 Download and verification instructions are available link:/download.html[on our download page].
 
+== Migration Notes
+
+This is a maintenance release within the 2.x series. If you are already running Shiro 2.x, upgrading to 2.0.5 should be straightforward with no breaking changes expected.
+
+If you are upgrading from Shiro 1.x, please review the link:/migration-guide.html[Migration Guide] for important changes between major versions.
+
 == Documentation
 
 For more information on link:/documentation.html[Shiro, please read the documentation.]
diff --git a/src/site/content/blog/2025/11/apache-shiro-206-released.adoc b/src/site/content/blog/2025/11/apache-shiro-206-released.adoc
index a5168ed8d..8d52f360c 100644
--- a/src/site/content/blog/2025/11/apache-shiro-206-released.adoc
+++ b/src/site/content/blog/2025/11/apache-shiro-206-released.adoc
@@ -47,6 +47,12 @@ You can learn more on link:https://github.com/apache/shiro/releases/tag/shiro-ro
 
 Download and verification instructions are available link:/download.html[on our download page].
 
+== Migration Notes
+
+This is a maintenance release within the 2.x series. If you are already running Shiro 2.x, upgrading to 2.0.6 should be straightforward with no breaking changes expected.
+
+If you are upgrading from Shiro 1.x, please review the link:/migration-guide.html[Migration Guide] for important changes between major versions.
+
 == Documentation
 
 For more information on link:/documentation.html[Shiro, please read the documentation.]
diff --git a/src/site/content/documentation.adoc b/src/site/content/documentation.adoc
index 473af0f1d..a6f77afaf 100644
--- a/src/site/content/documentation.adoc
+++ b/src/site/content/documentation.adoc
@@ -9,18 +9,24 @@
 
 == Introduction
 
-Helpful if read in order:
+This page serves as the central hub for all Apache Shiro documentation. Whether you are just getting started or looking for detailed reference material, you will find links to the appropriate resources here.
+
+=== New to Shiro?
+
+If you are new to Apache Shiro, we recommend reading these resources in order:
 
 * https://www.infoq.com/articles/apache-shiro[Application Security with Apache Shiro] - full intro article on InfoQ.com
-* link:10-minute-tutorial.html[10 Minute Tutorial]
-* link:webapp-tutorial.html[Beginner's Webapp Tutorial: a step-by-step tutorial to enable Shiro in a web application]
+* link:10-minute-tutorial.html[10 Minute Tutorial] - quick hands-on introduction
+* link:webapp-tutorial.html[Beginner's Webapp Tutorial] - step-by-step guide to enable Shiro in a web application
 * https://start.flowlogix.com[Flowlogix Starter] - generate Jakarta EE projects with Shiro support
 
+Once you understand the basics, explore the link:/guides.html[Guides] page for a complete learning path.
+
 == Apache Shiro Reference and API
 
 === Reference Manual
 
-* link:reference.html[Reference Manual]
+* link:reference.html[Reference Manual] - comprehensive reference covering all Shiro concepts and features
 
 === Guides - important Shiro concepts:
 
@@ -40,6 +46,10 @@ Apache Shiro ${versions.latestRelease} (link:download.html[Download])
 * link:https://github.com/apache/shiro/tree/shiro-root-${versions.latestRelease}/[Browse Source] (GitHub tag)
 * link:static/latest/[Maven Static Site]
 
+=== Upgrading?
+
+If you are upgrading from an earlier version of Shiro, see the link:migration-guide.html[Migration Guide] for important changes and upgrade instructions.
+
 ++++
 <@lendahand.lendahand />
 ++++
diff --git a/src/site/content/get-started.adoc b/src/site/content/get-started.adoc
index ef25b6275..710aa6b3a 100644
--- a/src/site/content/get-started.adoc
+++ b/src/site/content/get-started.adoc
@@ -33,4 +33,18 @@ If you're new to Apache Shiro, this short tutorial will show you how to set up a
 == Other Resources
 
 * *link:articles.html[Introductory Articles… and Beyond!]*
-Articles and Guides written by and for members of the Apache Shiro community.
\ No newline at end of file
+Articles and Guides written by and for members of the Apache Shiro community.
+
+== Next Steps
+
+Once you have completed the tutorials above, consider exploring these topics:
+
+* link:guides.html[All Guides] - Browse the complete collection of Shiro guides.
+* link:reference.html[Reference Documentation] - Comprehensive reference covering all Shiro features.
+* link:realm.html[Realms] - Learn how to connect Shiro to your user data sources.
+* link:migration-guide.html[Migration Guide] - If you are upgrading from an older Shiro version.
+
+== Need Help?
+
+* link:mailing-lists.html[Mailing Lists] - Ask questions and get help from the community.
+* link:issues.html[Issue Tracker] - Report bugs or request features.
\ No newline at end of file
diff --git a/src/site/content/guides.adoc b/src/site/content/guides.adoc
index cacd6aed9..5cb8e71e1 100644
--- a/src/site/content/guides.adoc
+++ b/src/site/content/guides.adoc
@@ -5,13 +5,41 @@
 :jbake-tags: guides, tutorials, how-to, learning
 :jbake-description: Collection of Apache Shiro guides and tutorials covering authentication, authorization, and security implementation patterns.
 :idprefix:
+:icons: font
 
-
-Here are some basic guides on how to use Shiro.
+This page collects the primary guides for learning Apache Shiro. Whether you are new to Shiro or looking to deepen your understanding, these guides provide practical, step-by-step instructions.
 
 Please post any errata to the user or dev mailing lists.
 
-* link:10-minute-tutorial.html[10 Minute Tutorial]
-* link:java-authentication-guide.html[Authentication Guide]
-* link:java-authorization-guide.html[Authorization Guide]
-* link:migration-guide.html[Migration Guide: Upgrading Shiro 1.x → 2.x → 3.x]
\ No newline at end of file
+== Getting Started
+
+If you are new to Shiro, start here:
+
+* link:10-minute-tutorial.html[10 Minute Tutorial] - A quick hands-on introduction to Shiro's core API and concepts.
+* link:tutorial.html[Your First Shiro Application] - Build a simple application secured by Shiro from scratch.
+* link:webapp-tutorial.html[Beginner's Webapp Tutorial] - A step-by-step guide to enabling Shiro in a web application.
+
+== Core Concepts
+
+Once you understand the basics, explore these guides to learn how authentication and authorization work in Shiro:
+
+* link:java-authentication-guide.html[Authentication Guide] - Learn how to verify user identity using Shiro's authentication API.
+* link:java-authorization-guide.html[Authorization Guide] - Understand how to control access to resources based on roles and permissions.
+
+== Advanced Topics
+
+After mastering the core concepts, consider these topics:
+
+* link:realm.html[Realm Guide] - Learn how Realms connect Shiro to your user data sources.
+* link:session-management.html[Session Management] - Understand how Shiro manages user sessions across environments.
+* link:cryptography.html[Cryptography] - Explore Shiro's simplified cryptography APIs.
+
+== Upgrading Shiro
+
+* link:migration-guide.html[Migration Guide: Upgrading Shiro 1.x → 2.x → 3.x] - Step-by-step instructions for upgrading between major Shiro versions.
+
+== See Also
+
+* link:reference.html[Reference Documentation] - Complete reference for all Shiro features.
+* link:documentation.html[Documentation Hub] - Central hub for all Shiro documentation resources.
+* link:articles.html[Community Articles] - Articles and tutorials contributed by the Shiro community.
\ No newline at end of file
diff --git a/src/site/content/java-authentication-guide.adoc b/src/site/content/java-authentication-guide.adoc
index 29e959aae..e564df68e 100644
--- a/src/site/content/java-authentication-guide.adoc
+++ b/src/site/content/java-authentication-guide.adoc
@@ -185,3 +185,13 @@ currentUser.logout(); //removes all identifying information and invalidates thei
 
 When you log out in Shiro it will close out the user session and removes any associated identity from the subject instance. If you're using RememberMe in a web environment, then `.logout()` will, by default, also delete the RememberMe cookie from the browser.
 
+== See Also
+
+Now that you understand authentication in Shiro, continue learning with these resources:
+
+* link:java-authorization-guide.html[Java Authorization Guide] - Learn how to control access to resources after authentication.
+* link:realm.html[Realms] - Learn how to connect Shiro to your user data sources.
+* link:authentication.html[Authentication Concepts] - Deeper dive into Shiro's authentication architecture.
+* link:authenticator.html[Authenticators] - Understand the component that performs authentication.
+* link:subject.html[Subject] - Learn more about the Subject API.
+
diff --git a/src/site/content/java-authorization-guide.adoc b/src/site/content/java-authorization-guide.adoc
index 5c5b4276c..7176c6e0d 100644
--- a/src/site/content/java-authorization-guide.adoc
+++ b/src/site/content/java-authorization-guide.adoc
@@ -216,4 +216,14 @@ For more information on JSP/GSP Tags please check out the link:jsp-tag-library.h
 
 == Caching Authorization
 
-TBD
\ No newline at end of file
+Shiro supports caching authorization data to improve performance. When authorization checks are performed frequently, caching avoids repeated lookups to the underlying data source. For more information on how caching works in Shiro, see the link:caching.html[Caching Documentation].
+
+== See Also
+
+Now that you understand authorization in Shiro, continue learning with these resources:
+
+* link:permissions.html[Permissions] - Deep dive into Shiro's permission model.
+* link:realm.html[Realms] - Learn how Realms provide authorization data.
+* link:authorization.html[Authorization Concepts] - Deeper dive into Shiro's authorization architecture.
+* link:authorizer.html[Authorizers] - Understand the component that performs authorization.
+* link:java-authentication-guide.html[Java Authentication Guide] - If you haven't already, learn about authentication.
\ No newline at end of file
diff --git a/src/site/content/reference.adoc b/src/site/content/reference.adoc
index d84326ad5..6e62ac286 100644
--- a/src/site/content/reference.adoc
+++ b/src/site/content/reference.adoc
@@ -5,6 +5,14 @@
 :jbake-tags: reference, documentation, manual, api
 :jbake-description: Complete Apache Shiro reference documentation covering core concepts, configuration, web integration, and advanced features.
 :idprefix:
+:icons: font
+
+This reference manual provides comprehensive documentation for all Apache Shiro features. Use this as your primary reference when implementing security in your applications.
+
+[TIP]
+====
+If you are new to Shiro, we recommend starting with the link:10-minute-tutorial.html[10 Minute Tutorial] or the link:guides.html[Guides] before diving into the reference material.
+====
 
 . Overview
 
@@ -52,3 +60,9 @@
 . Index
 
 ** link:terminology.html[Terminology]
+
+== See Also
+
+* link:guides.html[Guides] - Tutorials and step-by-step instructions.
+* link:documentation.html[Documentation Hub] - Central hub for all Shiro documentation.
+* link:migration-guide.html[Migration Guide] - For users upgrading between major versions.

From e6cb32ffe74c01e386b06f201e0bd5f7f2ecaa27 Mon Sep 17 00:00:00 2001
From: Ganesh Patil <7030871503ganeshpatil@gmail.com>
Date: Fri, 6 Feb 2026 10:11:58 +0530
Subject: [PATCH 10/10] docs: fix grammar and link format per review
 suggestions

---
 src/site/content/documentation.adoc | 2 +-
 src/site/content/forums.adoc        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/site/content/documentation.adoc b/src/site/content/documentation.adoc
index a6f77afaf..eb65327be 100644
--- a/src/site/content/documentation.adoc
+++ b/src/site/content/documentation.adoc
@@ -20,7 +20,7 @@ If you are new to Apache Shiro, we recommend reading these resources in order:
 * link:webapp-tutorial.html[Beginner's Webapp Tutorial] - step-by-step guide to enable Shiro in a web application
 * https://start.flowlogix.com[Flowlogix Starter] - generate Jakarta EE projects with Shiro support
 
-Once you understand the basics, explore the link:/guides.html[Guides] page for a complete learning path.
+Once you understand the basics, explore the link:guides.html[Guides] page for a complete learning path.
 
 == Apache Shiro Reference and API
 
diff --git a/src/site/content/forums.adoc b/src/site/content/forums.adoc
index 6202f54f1..9d5195c2a 100644
--- a/src/site/content/forums.adoc
+++ b/src/site/content/forums.adoc
@@ -5,7 +5,7 @@
 :jbake-tags: documentation, community
 :idprefix:
 
-For users that prefer to use browse the mailing lists with a browser can use https://lists.apache.org/[ASF Lists] (Pony Mail).
+For users that prefer to browse the mailing lists with a browser can use https://lists.apache.org/[ASF Lists] (Pony Mail).
 
 * link:++https://lists.apache.org/list.html?user@shiro.apache.org++[Shiro User Forum]