Merge pull request #860 from datamweb/improve-site-part2

Improve site part2
codeigniter4 · Sep 28, 2023 · b1adfa8 · b1adfa8
2 parents 7d6c685 + 48d0118
commit b1adfa8
Show file tree

Hide file tree

Showing 22 changed files with 242 additions and 167 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -13,5 +13,6 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
-      - run: pip install mkdocs-material
+      - run: pip3 install mkdocs-material
+      - run: pip3 install mkdocs-git-revision-date-localized-plugin
       - run: mkdocs gh-deploy --force
diff --git a/docs/addons/jwt.md b/docs/addons/jwt.md
@@ -1,7 +1,8 @@
 # JWT Authentication
 
-> **Note**
-> Shield now supports only JWS (Singed JWT). JWE (Encrypted JWT) is not supported.
+!!! note
+
+    Shield now supports only JWS (Singed JWT). JWE (Encrypted JWT) is not supported.
 
 ## What is JWT?
 
@@ -87,9 +88,10 @@ Configure **app/Config/AuthJWT.php** for your needs.
 
 ### Set the Default Claims
 
-> **Note**
-> A payload contains the actual data being transmitted, such as user ID, role,
-> or expiration time. Items in a payload is called *claims*.
+!!! note
+
+    A payload contains the actual data being transmitted, such as user ID, role,
+    or expiration time. Items in a payload is called *claims*.
 
 Set the default payload items to the property `$defaultClaims`.
 
@@ -121,8 +123,9 @@ with the following command:
 php -r 'echo base64_encode(random_bytes(32));'
 ```
 
-> **Note**
-> The secret key is used for signing and validating tokens.
+!!! note
+
+    The secret key is used for signing and validating tokens.
 
 ## Issuing JWTs
 
@@ -231,7 +234,7 @@ class LoginController extends BaseController
 
 You could send a request with the existing user's credentials by curl like this:
 
-```console
+```curl
 curl --location 'http://localhost:8080/auth/jwt' \
 --header 'Content-Type: application/json' \
 --data-raw '{"email" : "admin@example.jp" , "password" : "passw0rd!"}'
@@ -242,7 +245,7 @@ the `Authorization` header as a `Bearer` token.
 
 You could send a request with the `Authorization` header by curl like this:
 
-```console
+```curl
 curl --location --request GET 'http://localhost:8080/api/users' \
 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGllbGQgVGVzdCBBcHAiLCJzdWIiOiIxIiwiaWF0IjoxNjgxODA1OTMwLCJleHAiOjE2ODE4MDk1MzB9.DGpOmRPOBe45whVtEOSt53qJTw_CpH0V8oMoI_gm2XI'
 ```

diff --git a/docs/assets/css/dark_mode.css b/docs/assets/css/dark_mode.css
@@ -42,4 +42,33 @@
     .hljs-subst {
         color: #ddba52
     }
+
+    .md-typeset .note > .admonition-title,
+    .md-typeset .note > summary {
+        background-color: #0000001a;
+    }
+
+    .md-typeset .admonition.note,
+    .md-typeset details.note {
+        border-color: #675647;
+    }
+
+    .md-typeset .note > .admonition-title:before,
+    .md-typeset .note > summary:before {
+        background-color: #65686d;
+        -webkit-mask-image: var(--md-admonition-icon--note);
+        mask-image: var(--md-admonition-icon--note);
+    }
+
+    .md-typeset .admonition.warning,
+    .md-typeset details.warning {
+        border-color: #776144;
+    }
+
+    .md-typeset .warning > .admonition-title:before,
+    .md-typeset .warning > summary:before {
+        background-color: #d9913bc2;
+        -webkit-mask-image: var(--md-admonition-icon--warning);
+        mask-image: var(--md-admonition-icon--warning);
+    }
 }
diff --git a/docs/assets/js/curl.min.js b/docs/assets/js/curl.min.js
@@ -0,0 +1,14 @@
+/*! `curl` grammar compiled for Highlight.js 11.3.1 */
+(()=>{var e=(()=>{"use strict";return e=>{const n={className:"string",begin:/"/,
+end:/"/,contains:[e.BACKSLASH_ESCAPE,{className:"variable",begin:/\$\(/,
+end:/\)/,contains:[e.BACKSLASH_ESCAPE]}],relevance:0},a={className:"number",
+variants:[{begin:e.C_NUMBER_RE}],relevance:0};return{name:"curl",
+aliases:["curl"],keywords:"curl",case_insensitive:!0,contains:[{
+className:"literal",begin:/(--request|-X)\s/,contains:[{className:"symbol",
+begin:/(get|post|delete|options|head|put|patch|trace|connect)/,end:/\s/,
+returnEnd:!0}],returnEnd:!0,relevance:10},{className:"literal",begin:/--/,
+end:/[\s"]/,returnEnd:!0,relevance:0},{className:"literal",begin:/-\w/,
+end:/[\s"]/,returnEnd:!0,relevance:0},n,{className:"string",begin:/\\"/,
+relevance:0},{className:"string",begin:/'/,end:/'/,relevance:0
+},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,{match:/(\/[a-z._-]+)+/}]}}})()
+;hljs.registerLanguage("curl",e)})();
diff --git a/docs/customization/login_identifier.md b/docs/customization/login_identifier.md
@@ -21,8 +21,9 @@ This only works with the Session authenticator.
         'employee_id'
     ];
     ```
-    > **Warning**
-    > It is very important for security that if you add a new column for identifier, you must write a new **Validation Rules** and then set it using the [Customizing Validation Rules](./validation_rules.md) description.
+    !!! warning
+
+        It is very important for security that if you add a new column for identifier, you must write a new **Validation Rules** and then set it using the [Customizing Validation Rules](./validation_rules.md) description.
 
 3. Edit the login form to change the name of the default `email` input to the new field name.
 

diff --git a/docs/customization/table_names.md b/docs/customization/table_names.md
@@ -17,5 +17,6 @@ public array $tables = [
 
 Set the table names that you want in the array values.
 
-> **Note**
-> You must change the table names before running database migrations.
+!!! note
+
+    You must change the table names before running database migrations.
diff --git a/docs/customization/validation_rules.md b/docs/customization/validation_rules.md
@@ -39,83 +39,82 @@ Shield has the following rules for registration by default:
 ];
 ```
 
-> **Note**
-> If you customize the table names, the table names
-> (`users` and `auth_identities`) in the above rules will be automatically
-> changed. The rules are implemented in
-> `RegisterController::getValidationRules()`.
+!!! note
+
+    If you customize the table names, the table names(`users` and `auth_identities`) in the above rules will be automatically changed.
+    The rules are implemented in `RegisterController::getValidationRules()`.
 
 If you need a different set of rules for registration, you can specify them in your `Validation` configuration (**app/Config/Validation.php**) like:
 
 ```php
-    //--------------------------------------------------------------------
-    // Rules For Registration
-    //--------------------------------------------------------------------
-    public $registration = [
-        'username' => [
-            'label' => 'Auth.username',
-            'rules' => [
-                'required',
-                'max_length[30]',
-                'min_length[3]',
-                'regex_match[/\A[a-zA-Z0-9\.]+\z/]',
-                'is_unique[users.username]',
-            ],
-        ],
-        'email' => [
-            'label' => 'Auth.email',
-            'rules' => [
-                'required',
-                'max_length[254]',
-                'valid_email',
-                'is_unique[auth_identities.secret]',
-            ],
-        ],
-        'password' => [
-            'label' => 'Auth.password',
-            'rules' => 'required|max_byte[72]|strong_password[]',
-            'errors' => [
-                'max_byte' => 'Auth.errorPasswordTooLongBytes'
-            ]
+//--------------------------------------------------------------------
+// Rules For Registration
+//--------------------------------------------------------------------
+public $registration = [
+    'username' => [
+        'label' => 'Auth.username',
+        'rules' => [
+            'required',
+            'max_length[30]',
+            'min_length[3]',
+            'regex_match[/\A[a-zA-Z0-9\.]+\z/]',
+            'is_unique[users.username]',
         ],
-        'password_confirm' => [
-            'label' => 'Auth.passwordConfirm',
-            'rules' => 'required|matches[password]',
+    ],
+    'email' => [
+        'label' => 'Auth.email',
+        'rules' => [
+            'required',
+            'max_length[254]',
+            'valid_email',
+            'is_unique[auth_identities.secret]',
         ],
-    ];
+    ],
+    'password' => [
+        'label' => 'Auth.password',
+        'rules' => 'required|max_byte[72]|strong_password[]',
+        'errors' => [
+            'max_byte' => 'Auth.errorPasswordTooLongBytes'
+        ]
+    ],
+    'password_confirm' => [
+        'label' => 'Auth.passwordConfirm',
+        'rules' => 'required|matches[password]',
+    ],
+];
 ```
 
-> **Note**
-> If you customize the table names, set the correct table names in the
-> rules.
+!!! note
+
+    If you customize the table names, set the correct table names in the rules.
 
 ## Login
 
 Similar to the process for validation rules in the **Registration** section, you can add rules for the login form to **app/Config/Validation.php** and change the rules.
 
 ```php
-    //--------------------------------------------------------------------
-    // Rules For Login
-    //--------------------------------------------------------------------
-    public $login = [
-        // 'username' => [
-        //     'label' =>  'Auth.username',
-        //     'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]',
-        // ],
-        'email' => [
-            'label' => 'Auth.email',
-            'rules' => [
-                'required',
-                'max_length[254]',
-                'valid_email'
-            ],
-        ],
-        'password' => [
-            'label' => 'Auth.password',
-            'rules' => 'required|max_byte[72]',
-            'errors' => [
-                'max_byte' => 'Auth.errorPasswordTooLongBytes',
-            ]
+//--------------------------------------------------------------------
+// Rules For Login
+//--------------------------------------------------------------------
+public $login = [
+    // 'username' => [
+    //     'label' =>  'Auth.username',
+    //     'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]',
+    // ],
+    'email' => [
+        'label' => 'Auth.email',
+        'rules' => [
+            'required',
+            'max_length[254]',
+            'valid_email'
         ],
-    ];
+    ],
+    'password' => [
+        'label' => 'Auth.password',
+        'rules' => 'required|max_byte[72]',
+        'errors' => [
+            'max_byte' => 'Auth.errorPasswordTooLongBytes',
+        ]
+    ],
+];
 ```
diff --git a/docs/getting_started/concepts.md b/docs/getting_started/concepts.md
@@ -80,14 +80,13 @@ public $passwordValidators = [
 
 You use `strong_password` rule for password validation explained above.
 
-> **Note**
-> The `strong_password` rule only supports use cases to check the user's own password.
-> It fetches the authenticated user's data for **NothingPersonalValidator**
-> if the visitor is authenticated.
->
-> If you want to have use cases that set and check another user's password,
-> you can't use `strong_password`. You need to use `service('passwords')` directly
-> to check the password.
->
-> But remember, it is not good practice to set passwords for other users.
-> This is because the password should be known only by that user.
+!!! note
+
+    The `strong_password` rule only supports use cases to check the user's own password.
+    It fetches the authenticated user's data for **NothingPersonalValidator**
+    if the visitor is authenticated.
+    If you want to have use cases that set and check another user's password,
+    you can't use `strong_password`. You need to use `service('passwords')` directly
+    to check the password.
+    But remember, it is not good practice to set passwords for other users.
+    This is because the password should be known only by that user.
diff --git a/docs/getting_started/install.md b/docs/getting_started/install.md
@@ -62,10 +62,10 @@ Require it with an explicit version constraint allowing its desired stability.
     php spark shield:setup
     ```
 
-    > **Note**
-    > If you want to customize table names, you must change the table names
-    > before running database migrations.
-    > See [Customizing Table Names](../customization/table_names.md).
+    !!! note
+
+        If you want to customize table names, you must change the table names before running database migrations.
+        See [Customizing Table Names](../customization/table_names.md).
 
 2. Configure **app/Config/Email.php** to allow Shield to send emails with the [Email Class](https://codeigniter.com/user_guide/libraries/email.html).
 
@@ -140,10 +140,10 @@ your project.
 
 5. **Migration** Run the migrations.
 
-    > **Note**
-    > If you want to customize table names, you must change the table names
-    > before running database migrations.
-    > See [Customizing Table Names](../customization/table_names.md).
+    !!! note
+
+        If you want to customize table names, you must change the table names before running database migrations.
+        See [Customizing Table Names](../customization/table_names.md).
 
     ```console
     php spark migrate --all

diff --git a/docs/guides/api_hmac_keys.md b/docs/guides/api_hmac_keys.md
@@ -1,16 +1,18 @@
 # Protecting an API with HMAC Keys
 
-> **Note**
-> For the purpose of this documentation and to maintain a level of consistency with the Authorization Tokens,
+!!! note
+
+    For the purpose of this documentation and to maintain a level of consistency with the Authorization Tokens,
     the term "Token" will be used to represent a set of API Keys (key and secretKey).
 
 HMAC Keys can be used to authenticate users for your own site, or when allowing third-party developers to access your
 API. When making requests using HMAC keys, the token should be included in the `Authorization` header as an
 `HMAC-SHA256` token.
 
-> **Note**
-> By default, `$authenticatorHeader['hmac']` is set to `Authorization`. You can change this value by
-> setting the `$authenticatorHeader['hmac']` value in the **app/Config/AuthToken.php** config file.
+!!! note
+
+    By default, `$authenticatorHeader['hmac']` is set to `Authorization`. You can change this value by
+    setting the `$authenticatorHeader['hmac']` value in the **app/Config/AuthToken.php** config file.
 
 Tokens are issued with the `generateHmacToken()` method on the user. This returns a
 `CodeIgniter\Shield\Entities\AccessToken` instance. These shared keys are saved to the database in plain text. The
@@ -63,9 +65,10 @@ $token = $user->generateHmacToken('token-name', ['users-read']);
 return json_encode(['key' => $token->secret, 'secretKey' => $token->secret2]);
 ```
 
-> **Note**
-> At this time, scope names should avoid using a colon (`:`) as this causes issues with the route filters being
-> correctly recognized.
+!!! note
+
+    At this time, scope names should avoid using a colon (`:`) as this causes issues with the route filters being
+    correctly recognized.
 
 When handling incoming requests you can check if the token has been granted access to the scope with the `hmacTokenCan()` method.
 
@@ -111,5 +114,6 @@ parses the raw token and looks it up the `key` portion in the database. Once fou
 to validate the remainder of the Authorization raw token.  If it passes the signature test it can determine the correct user,
 which will then be available through an `auth()->user()` call.
 
-> **Note**
-> Currently only a single scope can be used on a route filter. If multiple scopes are passed in, only the first one is checked.
+!!! note
+
+    Currently only a single scope can be used on a route filter. If multiple scopes are passed in, only the first one is checked.