Add doc validation workflow + fix linting errors

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+  push:
+    branches:
+      - 4.x
+    paths:
+      - 'docs/**'
+      - '.github/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/**'
+
+jobs:
+  validate:
+    uses: cakephp/.github/.github/workflows/docs-validation.yml@doc-workflows
+    with:
+      docs-path: 'docs'
+      vitepress-path: 'docs/.vitepress'
+      enable-config-js-check: true
+      enable-json-lint: true
+      enable-toc-check: true
+      enable-spell-check: true
+      enable-markdown-lint: true
+      enable-link-check: true
+      tools-ref: 'doc-workflows'

docs/en/authentication-component.md

@@ -4,7 +4,7 @@ You can use the `AuthenticationComponent` to access the result of
 authentication, get user identity and logout user. Load the component in your
 `AppController::initialize()` like any other component:
 
-``` php
+```php
 $this->loadComponent('Authentication.Authentication', [
     'logoutRedirect' => '/users/login'  // Default is false
 ]);
@@ -14,7 +14,7 @@ Once loaded, the `AuthenticationComponent` will require that all actions have an
 authenticated user present, but perform no other access control checks. You can
 disable this check for specific actions using `allowUnauthenticated()`:
 
-``` php
+```php
 // In your controller's beforeFilter method.
 $this->Authentication->allowUnauthenticated(['view']);
 ```
@@ -24,13 +24,13 @@ $this->Authentication->allowUnauthenticated(['view']);
 You can get the authenticated user identity data using the authentication
 component:
 
-``` php
+```php
 $user = $this->Authentication->getIdentity();
 ```
 
 You can also get the identity directly from the request instance:
 
-``` php
+```php
 $user = $request->getAttribute('identity');
 ```
 
@@ -39,7 +39,7 @@ $user = $request->getAttribute('identity');
 You can check if the authentication process was successful by accessing the
 result object:
 
-``` php
+```php
 // Using Authentication component
 $result = $this->Authentication->getResult();
 
@@ -73,7 +73,7 @@ the included authenticators don't put anything in here.
 
 To log an identity out just do:
 
-``` php
+```php
 $this->Authentication->logout();
 ```
 
@@ -83,13 +83,13 @@ in either case.
 
 Alternatively, instead of the component you can also use the service to log out:
 
-``` php
+```php
 $return = $request->getAttribute('authentication')->clearIdentity($request, $response);
 ```
 
 The result returned will contain an array like this:
 
-``` php
+```php
 [
     'response' => object(Cake\Http\Response) { ... },
     'request' => object(Cake\Http\ServerRequest) { ... },
@@ -108,7 +108,7 @@ By default `AuthenticationComponent` will automatically enforce an identity to
 be present during the `Controller.startup` event. You can have this check
 applied during the `Controller.initialize` event instead:
 
-``` php
+```php
 // In your controller's initialize() method.
 $this->loadComponent('Authentication.Authentication', [
     'identityCheckEvent' => 'Controller.initialize',
@@ -118,6 +118,6 @@ $this->loadComponent('Authentication.Authentication', [
 You can also disable identity checks entirely with the `requireIdentity`
 option or by calling `disableIdentityCheck` from the controller's `beforeFilter()` method itself:
 
-``` php
+```php
 $this->Authentication->disableIdentityCheck();
 ```

docs/en/authenticators.md

@@ -30,7 +30,7 @@
 A default `TokenIdentifier` is provided that looks up users by their `id` field,
 so minimal configuration is required:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession');
 ```
 
@@ -43,15 +43,15 @@
 For custom lookup fields, the `idField` and `identifierKey` options propagate
 to the default identifier automatically:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession', [
     'idField' => 'uuid',
 ]);
 ```
 
 You can also provide a fully custom identifier configuration if needed:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession', [
     'identifier' => [
         'Authentication.Token' => [
@@ -109,7 +109,7 @@
 
 An example of getting a token from a header, or query string would be:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.Token', [
     'queryParam' => 'token',
     'header' => 'Authorization',
@@ -122,7 +122,7 @@
 
 The token will always be passed to the configured identifier as follows:
 
-``` php
+```php
 [
     'token' => '{token-value}',
 ]
@@ -158,7 +158,7 @@
 For enhanced security one can instead use the `RS256` asymmetric key algorithm.
 You can generate the required keys for that as follows:
 
-``` text
+```text
 # generate private key
 openssl genrsa -out config/jwt.key 1024
 # generate public key
@@ -175,7 +175,7 @@
 
 Add the following to your `Application` class:
 
-``` php
+```php
 public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
 {
     $service = new AuthenticationService();
@@ -193,7 +193,7 @@
 
 In your `UsersController`:
 
-``` php
+```php
 use Firebase\JWT\JWT;
 
 public function login(): void
@@ -221,7 +221,7 @@
 
 Using a JWKS fetched from an external JWKS endpoint is supported as well:
 
-``` php
+```php
 // Application.php
 public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
 {
@@ -257,7 +257,7 @@
 Beside from sharing the public key file to external application, you can
 distribute it via a JWKS endpoint by configuring your app as follows:
 
-``` php
+```php
 // config/routes.php
 $builder->setExtensions('json');
 $builder->connect('/.well-known/{controller}', [
@@ -375,7 +375,7 @@
 explicitly logged out via `AuthenticationComponent::logout()` the
 authentication cookie is **also destroyed**. An example configuration would be:
 
-``` php
+```php
 // In Application::getAuthenticationService()
 
 // Reuse fields in multiple authenticators.
@@ -404,7 +404,7 @@
 
 You'll also need to add a checkbox to your login form to have cookies created:
 
-``` php
+```php
 // In your login view
 <?= $this->Form->control('remember_me', ['type' => 'checkbox']);
 ```
@@ -420,7 +420,7 @@
 [Shibboleth](https://shibboleth.atlassian.net/wiki/spaces/CONCEPT/overview)
 and similar SAML 1.1 implementations. An example configuration is:
 
-``` php
+```php
 // Configure a token identifier that maps `USER_ID` to the
 // username column
 $identifier = [
@@ -442,7 +442,7 @@
 ]);
 ```
 
 
 ## Events
 
 There is only one event that is fired by authentication:
@@ -505,7 +505,7 @@
 After a user has been authenticated you may want to inspect or interact with the
 Authenticator that successfully authenticated the user:
 
-``` php
+```php
 // In a controller action
 $service = $this->request->getAttribute('authentication');
 
@@ -515,7 +515,7 @@
 
 You can also get the identifier that identified the user as well:
 
-``` php
+```php
 // In a controller action
 $service = $this->request->getAttribute('authentication');
 
@@ -530,7 +530,7 @@
 authentication credentials are missing or invalid. This is necessary as these
 authenticators must send specific challenge headers in the response:
 
-``` php
+```php
 use Authentication\AuthenticationService;
 
 // Instantiate the service
@@ -569,7 +569,7 @@
 You can also pass the current request target URI as a query parameter
 using the `queryParam` option:
 
-``` php
+```php
 // In the getAuthenticationService() method of your src/Application.php
 
 $service = new AuthenticationService();
@@ -584,7 +584,7 @@
 Then in your controller's login method you can use `getLoginRedirect()` to get
 the redirect target safely from the query string parameter:
 
 ``` php
 public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
@@ -613,7 +613,7 @@
 this flow you can return different authentication services based on the URL
 path, or any other request attribute:
 
-``` php
+```php
 public function getAuthenticationService(
     ServerRequestInterface $request
 ): AuthenticationServiceInterface {

docs/en/contents.md

@@ -1,6 +1,6 @@
 # Contents
 
-### CakePHP Authentication
+## CakePHP Authentication
 
 - [Quick Start](index)
 - [Authenticators](authenticators)

docs/en/identifiers.md

@@ -4,7 +4,7 @@ Identifiers will identify a user or service based on the information
 that was extracted from the request by the authenticators. A holistic example of
 using the Password Identifier looks like:
 
-``` php
+```php
 $identifier = [
     'Authentication.Password' => [
         'fields' => [
@@ -118,7 +118,7 @@ Configuration options:
 
 Callback identifiers can either return `null|ArrayAccess` for simple results, or an `Authentication\Authenticator\Result` if you want to forward error messages:
 
-``` php
+```php
 // A simple callback identifier
 $identifier = [
     'Authentication.Callback' => [
@@ -185,7 +185,7 @@ reside under `App\Identifier\Resolver` namespace.
 
 Resolver can be configured using `resolver` config option:
 
-``` php
+```php
 $identifier = [
     'Authentication.Password' => [
         'resolver' => [
@@ -200,7 +200,7 @@ $identifier = [
 
 Or pass the constructed resolver directly into the identifier configuration:
 
-``` php
+```php
 $resolver = new \App\Identifier\Resolver\CustomResolver();
 $identifier = [
     'Authentication.Password' => [

docs/en/identity-object.md

@@ -7,7 +7,7 @@ called to get the primary id value of the current log in identity.
 The reason this object exists is to provide an interface that makes it
 implementations/sources:
 
-``` php
+```php
 // Service
 $authenticationService
     ->getIdentity()
@@ -28,7 +28,7 @@ The identity object provides ArrayAccess but as well a `get()` method to
 access data. It is strongly recommended to use the `get()` method over array
 access because the get method is aware of the field mapping:
 
-``` php
+```php
 $identity->get('email');
 $identity->get('username');
 ```
@@ -38,7 +38,7 @@ The `get()` method can also be type-hinted via IDE meta file, e.g. through
 
 If you want, you can use property access, however:
 
-``` text
+```text
 $identity->email;
 $identity->username;
 ```
@@ -48,7 +48,7 @@ is pretty useful if the identifier of the identity is a non-conventional
 `id` field or if you want to map other fields to more generic and
 common names:
 
-``` php
+```php
 $identity = new Identity($data, [
     'fieldMap' => [
         'id' => 'uid',
@@ -69,7 +69,7 @@ create your own identity object, your object must implement the
 If you’d like to continue using your existing User class with this
 plugin you can implement the `Authentication\IdentityInterface`:
 
-``` php
+```php
 namespace App\Model\Entity;
 
 use Authentication\IdentityInterface;
@@ -103,7 +103,7 @@ If your identifiers cannot have their resulting objects modified to
 implement the `IdentityInterface` you can implement a custom decorator
 that implements the required interface:
 
-``` php
+```php
 // You can use a callable...
 $identityResolver = function ($data) {
     return new MyCustomIdentity($data);

docs/en/impersonation.md

@@ -10,7 +10,7 @@
 `AuthenticationComponent`. To impersonate a user you first need to load that
 user from your application's database:
 
-``` php
+```php
 // In a controller
 public function impersonate(): \Cake\Http\Response
 {
@@ -44,7 +44,7 @@
 Once you are done impersonating a user, you can then end impersonation and revert
 back to your previous identity using `AuthenticationComponent`:
 
-``` php
+```php
 // In a controller
 public function revertIdentity(): \Cake\Http\Response
 {
@@ -64,6 +64,6 @@
 
 There are a few limitations to impersonation.
 
 1.  Your application must be using the `Session` authenticator.
 2.  You cannot impersonate another user while impersonation is active. Instead
     you must `stopImpersonating()` and then start it again.