improve docs

src/docs/reference/modules/UrlRewriting/README.md

@@ -1,20 +1,17 @@
 # URL Rewriting (`OrchardCore.UrlRewriting`)
 
-The URL Rewriting module enables you to configure URL rewrites and redirects for incoming HTTP requests, significantly enhancing your site's SEO and user experience. This allows you to control how URLs are handled and presented to users and search engines.
+The URL Rewriting feature allows you to configure URL rewrites and redirects for incoming HTTP requests, significantly improving your site's SEO and user experience. This feature enables you to control how URLs are presented to both users and search engines.
 
-After enabling this feature, you can manage your rewrite rules by navigating to **Configuration** >> **URL Rewriting**.
+Once enabled, you can manage your rewrite rules by navigating to **Configuration** >> **URL Rewriting**. The order of these rules is crucial, as they are processed sequentially based on their position. The first listed rule is evaluated first for matches. To facilitate this, the UI provides a drag-and-drop feature for easy sorting of the rules.
 
 ## Available Rule Sources
 
-### Redirect Rule
+| Rule Type     | Description                                                                                                                                                       | Example                                                    |
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
+| **Redirect Rule** | The **Redirect Rule** is utilized to send users from one URL to another, which is particularly beneficial for maintaining SEO integrity when URLs change.        | Permanently redirect users from `/about-us` to `/about`.   |
+| **Rewrite Rule**  | The **Rewrite Rule** allows you to modify the incoming request URL without changing the URL displayed in the browser's address bar, aiding in content organization. | Change requests for media files from `/img/` to `/media/`. |
 
-The **Redirect Rule** is utilized to send users from one URL to another. This is particularly beneficial for maintaining SEO integrity when URLs change. For example, a redirect rule can permanently redirect users from `/about-us` to `/about`, ensuring both users and search engines are directed to the correct page.
-
-### Rewrite Rule
-
-The **Rewrite Rule** allows you to modify the incoming request URL without changing the URL displayed in the browser's address bar. This can be advantageous for organizing content and serving files more effectively. For instance, a rewrite rule can change requests for media files from the `/img/` prefix to `/media/`, thus creating a consistent structure for accessing media files.
-
-## Adding Rule Sources
+## Creating Additional Rule Sources
 
 To add a new rule source, implement the `IUrlRewriteRuleSource` interface. This implementation will allow you to register a new rule source and provide a mechanism to configure these rules.
 
@@ -35,6 +32,8 @@ In this example, `CustomRuleSource` represents your implementation of `IUrlRewri
 
 ## Recipes
 
+The recipe will be accessible only if the OrchardCore.Recipes.Core feature is enabled.
+
 ### Recipe for Creating and Updating Rules
 
 The `UrlRewriting` step allows you to create or update URL rewrite rules easily. The example below illustrates how to create a rule that permanently redirects users from `/about-us` to `/about`, along with another rule that serves all media files using the `/img/` prefix instead of `/media/`.
@@ -73,20 +72,28 @@ The `UrlRewriting` step allows you to create or update URL rewrite rules easily.
 
 ### Redirect Rule Properties
 
-- **Id**: A unique identifier for the redirect rule. If the specified Id matches an existing rule, that rule will be updated with the provided properties. To create a new rule, leave the Id property empty or specify a unique value that does not match any existing rule.
-- **Name**: A descriptive name for the rule (e.g., `"Redirect about-us to about"`).
+- **Id**: A unique identifier for the redirect rule. If the specified ID matches an existing rule, that rule will be updated with the provided properties. To create a new rule, leave the ID property empty or specify a unique value that does not match any existing rule.
+- **Name**: A descriptive name for the rule (e.g., "Redirect about-us to about").
 - **Pattern**: The URL pattern to match (e.g., `^/about-us$` for an exact match).
-- **SubstitutionPattern**: The target URL to redirect to (e.g., `/about`).
-- **IsCaseInsensitive**: When set to `true`, matching is case-insensitive.
-- **QueryStringPolicy**: To append the query string to the new URL, use 'Append'. To ignore the query string during the redirect, select 'Drop'.
-- **RedirectType**: Specifies the HTTP status code for the redirect. `MovedPermanently` (HTTP 301) indicates a permanent redirect.
+- **SubstitutionPattern**: The target URL to which the redirect will occur (e.g., `/about`).
+- **IsCaseInsensitive**: When set to `true`, the pattern matching will be case-insensitive.
+- **QueryStringPolicy**: Determines how query strings are handled during the redirect:
+  - **Append**: Appends the original query string to the new URL.
+  - **Drop**: Ignores the query string during the redirect.
+- **RedirectType**: Specifies the HTTP status code for the redirect. The following values are supported:
+  - **Found**: (HTTP 302) Indicates a temporary redirect.
+  - **MovedPermanently**: (HTTP 301) Indicates a permanent redirect, instructing clients to update their bookmarks or links to the new URL.
+  - **TemporaryRedirect**: (HTTP 307) Similar to 302 but ensures that the request method remains unchanged (e.g., a POST request remains a POST).
+  - **PermanentRedirect**: (HTTP 308) Indicates that the resource has been permanently moved to a new URL.
 
 ### Rewrite Rule Properties
 
-- **Id**: A unique identifier for the rewrite rule. Similar to redirect rules, if the specified Id matches an existing rule, that rule will be updated. Leave the Id empty to create a new rule.
-- **Name**: A descriptive name for the rule (e.g., `"Serve media URLs from img"`).
-- **Pattern**: The URL pattern to match (e.g., `^/img/(.*)$` to match any URL starting with `/img/`).
+- **Id**: A unique identifier for the rewrite rule. If the specified ID matches an existing rule, that rule will be updated. To create a new rule, leave the ID empty.
+- **Name**: A descriptive name for the rule (e.g., "Serve media URLs from img").
+- **Pattern**: The URL pattern to match (e.g., `^/img/(.*)$` matches any URL starting with `/img/`).
 - **SubstitutionPattern**: The target URL for the rewrite (e.g., `/media/$1`, where `$1` captures the matched portion of the original URL).
-- **IsCaseInsensitive**: When set to `true`, matching is case-insensitive.
-- **QueryStringPolicy**: To append the query string to the new URL, use 'Append'. To ignore the query string during the redirect, select 'Drop'.
-- **SkipFurtherRules**: When set to `true`, subsequent rules will not be processed if this rule matches.
+- **IsCaseInsensitive**: When set to `true`, the pattern matching will be case-insensitive.
+- **QueryStringPolicy**: Determines how query strings are handled during the rewrite:
+  - **Append**: Appends the original query string to the new URL.
+  - **Drop**: Ignores the query string during the rewrite.
+- **SkipFurtherRules**: When set to `true`, any subsequent rules will not be processed if this rule matches.