Formatting improvements

docs/basic-usage/middleware.md

@@ -8,28 +8,22 @@ weight: 11
 For checking against a single permission (see Best Practices) using `can`, you can use the built-in Laravel middleware provided by `\Illuminate\Auth\Middleware\Authorize::class` like this:
 
 ```php
-Route::group(['middleware' => ['can:publish articles']], function () {
-    //
-});
-```
-
-Since Laravel v10.9, you can also call this middleware with a static method.
+Route::group(['middleware' => ['can:publish articles']], function () { ... });
 
-```php
-Route::group(['middleware' => [\Illuminate\Auth\Middleware\Authorize::using('publish articles')]], function () {
-    //
-});
+// or with static method (requires Laravel 10.9+)
+Route::group(['middleware' => [\Illuminate\Auth\Middleware\Authorize::using('publish articles')]], function () { ... });
 ```
 
 ## Package Middleware
 
-**See a typo? Note that since v6 the _'Middleware'_ namespace is singular. Prior to v6 it was _'Middlewares'_. Time to upgrade your app!**
+**See a typo? Note that since v6 the _'Middleware'_ namespace is singular. Prior to v6 it was _'Middlewares'_. Time to upgrade your implementation!**
 
 This package comes with `RoleMiddleware`, `PermissionMiddleware` and `RoleOrPermissionMiddleware` middleware.
 
 You can register their aliases for easy reference elsewhere in your app:
 
-In Laravel 11 open `/bootstrap/app.php` and register it there:
+In Laravel 11 open `/bootstrap/app.php` and register them there:
+
 ```php
     ->withMiddleware(function (Middleware $middleware) {
         $middleware->alias([
@@ -41,6 +35,7 @@ In Laravel 11 open `/bootstrap/app.php` and register it there:
 ```
 
 In Laravel 9 and 10 you can add them in `app/Http/Kernel.php`:
+
 ```php
 // Laravel 9 uses $routeMiddleware = [
 //protected $routeMiddleware = [
@@ -54,92 +49,62 @@ protected $middlewareAliases = [
 ```
 
 ### Middleware Priority
-If your app is triggering *404 Not Found* responses when a *403 Not Authorized* response might be expected, it might be a middleware priority clash. Explore reordering priorities so that this package's middleware runs before Laravel's `SubstituteBindings` middleware. (See [Middleware docs](https://laravel.com/docs/master/middleware#sorting-middleware) ). In Laravel 11 you could explore `$middleware->prependToGroup()` instead.
+If your app is triggering *404 Not Found* responses when a *403 Not Authorized* response might be expected, it might be a middleware priority clash. Explore reordering priorities so that this package's middleware runs before Laravel's `SubstituteBindings` middleware. (See [Middleware docs](https://laravel.com/docs/master/middleware#sorting-middleware) ). 
 
+In Laravel 11 you could explore `$middleware->prependToGroup()` instead. See the Laravel Documentation for details.
 
-## Middleware via Routes
 
-Then you can protect your routes using middleware rules:
+## Using Middleware in Routes and Controllers
 
-```php
-Route::group(['middleware' => ['role:manager']], function () {
-    //
-});
+After you have registered the aliases as shown above, you can use them in your Routes and Controllers much the same way you use any other middleware: 
 
-// for a specific guard:
-Route::group(['middleware' => ['role:manager,api']], function () {
-    //
-});
+### Routes
 
-Route::group(['middleware' => ['permission:publish articles']], function () {
-    //
-});
+```php
+Route::group(['middleware' => ['role:manager']], function () { ... });
+Route::group(['middleware' => ['permission:publish articles']], function () { ... });
+Route::group(['middleware' => ['role_or_permission:publish articles']], function () { ... });
 
-Route::group(['middleware' => ['role:manager','permission:publish articles']], function () {
-    //
-});
+// for a specific guard:
+Route::group(['middleware' => ['role:manager,api']], function () { ... });
 
-Route::group(['middleware' => ['role_or_permission:publish articles']], function () {
-    //
-});
+// multiple middleware
+Route::group(['middleware' => ['role:manager','permission:publish articles']], function () { ... });
 ```
 
 You can specify multiple roles or permissions with a `|` (pipe) character, which is treated as `OR`:
 
 ```php
-Route::group(['middleware' => ['role:manager|writer']], function () {
-    //
-});
-
-Route::group(['middleware' => ['permission:publish articles|edit articles']], function () {
-    //
-});
+Route::group(['middleware' => ['role:manager|writer']], function () { ... });
+Route::group(['middleware' => ['permission:publish articles|edit articles']], function () { ... });
+Route::group(['middleware' => ['role_or_permission:manager|edit articles']], function () { ... });
 
 // for a specific guard
-Route::group(['middleware' => ['permission:publish articles|edit articles,api']], function () {
-    //
-});
-
-Route::group(['middleware' => ['role_or_permission:manager|edit articles']], function () {
-    //
-});
+Route::group(['middleware' => ['permission:publish articles|edit articles,api']], function () { ... });
 ```
 
-## Middleware with Controllers
-
-You can protect your controllers similarly, by setting desired middleware in the constructor:
+### Controllers
 
 ```php
 public function __construct()
 {
     $this->middleware(['role:manager','permission:publish articles|edit articles']);
-}
-```
-
-```php
-public function __construct()
-{
+    // or
     $this->middleware(['role_or_permission:manager|edit articles']);
+    // or with specific guard
+    $this->middleware(['role_or_permission:manager|edit articles,api']);
 }
 ```
 
-(You can use Laravel's Model Policy feature with your controller methods. See the Model Policies section of these docs.)
+You can also use Laravel's Model Policy feature in your controller methods. See the Model Policies section of these docs.
 
-## Use middleware static methods
+## Middleware via Static Methods
 
-All of the middleware can also be applied by calling the static `using` method,
-which accepts either a `|`-separated string or an array as input.
+All of the middleware can also be applied by calling the static `using` method, which accepts either an array or a `|`-separated string as input.
 
 ```php
-Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleMiddleware::using('manager')]], function () {
-    //
-});
-
-Route::group(['middleware' => [\Spatie\Permission\Middleware\PermissionMiddleware::using('publish articles|edit articles')]], function () {
-    //
-});
-
-Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleOrPermissionMiddleware::using(['manager', 'edit articles'])]], function () {
-    //
-});
+Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleMiddleware::using('manager')]], function () { ... });
+Route::group(['middleware' => [\Spatie\Permission\Middleware\PermissionMiddleware::using('publish articles|edit articles')]], function () { ... });
+Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleOrPermissionMiddleware::using(['manager', 'edit articles'])]], function () { ... });
 ```
+