This is an automated email from the ASF dual-hosted git repository.
lprimak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/main by this push:
new be7091b97 docs: improve documentation content structure (#292)
be7091b97 is described below
commit be7091b976439602dfab76f3e29b7a1316591cee
Author: Ganesh Patil <[email protected]>
AuthorDate: Sun Oct 11 11:33:19 2026 +0530
docs: improve documentation content structure (#292)
* docs: migrate issue tracking to GitHub Issues and Discussions
* review comments
* docs: address PR review feedback
* docs: complete authenticator and authorizer documentation
* 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
* fix: update issues.adoc to use GitHub Issues instead of Jira
* docs: clarify FirstSuccessfulStrategy description for better clarity
* 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.
* docs: improve documentation content structure and navigation
* docs: fix grammar and link format per review suggestions
* cleanup
---------
Co-authored-by: lprimak <[email protected]>
---
src/site/content/authenticator.adoc | 11 +++++++
src/site/content/authorizer.adoc | 12 ++++++++
src/site/content/documentation.adoc | 18 ++++++++---
src/site/content/get-started.adoc | 16 +++++++++-
src/site/content/guides.adoc | 40 +++++++++++++++++++++----
src/site/content/java-authentication-guide.adoc | 10 +++++++
src/site/content/java-authorization-guide.adoc | 12 +++++++-
src/site/content/reference.adoc | 14 +++++++++
8 files changed, 121 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/documentation.adoc
b/src/site/content/documentation.adoc
index 473af0f1d..eb65327be 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..da76b5cce 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.
diff --git a/src/site/content/guides.adoc b/src/site/content/guides.adoc
index cacd6aed9..b9d9c7ea9 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.
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..3ba77de99 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.
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.
