docs(permissions): The "permission" pages needs rework to be more readable #430

docs/permission/overview.md

@@ -5,15 +5,46 @@ keywords: [permissions, Casbin]
 authors: [seriouszyx, MagicalSheep]
 ---
 
-## Introduction
-
 All users associated with a single Casdoor organization share access to the organization's applications. However, there may be instances where you want to restrict user access to certain applications or specific resources within an application. In such cases, you can utilize the `Permission` feature provided by [Casbin](https://casbin.org/).
 
-Before delving deeper into the topic, it is important to have a basic understanding of how Casbin works and its related concepts, such as Models, Policies, and Adapters. In a nutshell, a Model defines the structure of your permission policies and the criteria for matching requests against these policies and their outcomes. A Policy, on the other hand, describes the specific permission rules. Once Casbin has the necessary Model and Policy information, it can enforce permission control on incoming requests. Acting as an abstraction layer, an Adapter shields Casbin's executor from the source of the Policy, allowing the storage of Policies in various locations like files or databases.
+## Casbin Fundamentals
+
+- **Model**
+
+  defines the structure of your permission policies and the criteria for matching requests against these policies and their outcomes.
+
+- **Policy**
+
+  describes the specific permission rules. Once Casbin has the necessary Model and Policy information, it can enforce permission control on incoming requests.
+
+- **Adapter**
+
+  shields Casbin's executor from the source of the Policy, allowing the storage of Policies in various locations like files or databases.
+
+## Configuring Permissions
+
+   you can add a Model for your organization in the Model configuration item within `the Casdoor Web UI`, and a Policy for your organization in the Permission configuration item.
+
+- **Model Configuration**
+
+    The [Casbin Online Editor](https://casbin.org/editor) can provide you with Model and Policy files tailored to your specific usage scenarios. You can effortlessly import the Model file into Casdoor through its Web UI for use by the built-in Casbin.
+
+    Or you can add it manually in casbin's ui interface.
+
+- **Policy Configuration**
+
+    for the Policy (i.e., the `Permission` configuration item in the Casdoor Web UI), further instructions are necessary, which will be discussed later.
+
+## Casdoor's Exposed Casbin API
+
+   Just as your application needs to enforce permission control through Casdoor's built-in Casbin, Casdoor itself utilizes its own Model and Policy to regulate access permissions for the API interfaces through Casbin.
+   Though Casdoor can call Casbin from internal code, external applications cannot.
 
-Returning to the subject of permission configuration in Casdoor, you can add a Model for your organization in the `Model` configuration item within the Casdoor Web UI, and a Policy for your organization in the `Permission` configuration item. The [Casbin Online Editor](https://casbin.org/editor) can provide you with Model and Policy files tailored to your specific usage scenarios. You can effortlessly import the Model file into Casdoor through its Web UI for use by the built-in Casbin. However, for the Policy (i.e., the `Permission` configuration item in the Casdoor Web UI), further instructions are necessary, which will be discussed later.
+- **usage**
+
+  for external applications to call the built-in Casbin.
 
-Just as your application needs to enforce permission control through Casdoor's built-in Casbin, Casdoor itself utilizes its own Model and Policy to regulate access permissions for the API interfaces through Casbin. Though Casdoor can call Casbin from internal code, external applications cannot. As a solution, Casdoor exposes an API for external applications to call the built-in Casbin. We will provide definitions of these API interfaces and instructions on how to use them shortly.
+In subsequent chapters, We will provide definitions of these API interfaces and instructions on how to use them.
 
 Towards the end of this chapter, we will showcase a practical example to demonstrate how Casdoor works in collaboration with external applications for permission control.
 

docs/permission/permission-configuration.md

@@ -4,20 +4,31 @@ description: Using exposed Casbin APIs to manage users' access rights in an orga
 keywords: [permissions, Casbin]
 authors: [MagicalSheep]
 ---
-
-Let's explain each item in the Permission Configuration page.
+### Each Item in the Permission Configuration Page
 
 - `Organization`: The name of the organization to which the policy belongs. An organization can have multiple permission policy files.
 - `Name`: The globally unique name of the permission policy in the organization. It is used to identify the policy file.
 - `Display name`: Not important.
 - `Model`: The name of the model file that describes the structure and matching patterns of the permission policy.
-- `Adapter`: **Attention!** In the current version, this field describes the name of the database table that stores the permission policy, rather than the name of the adapter configured in the Adapter menu item in the Casdoor Web UI. Casdoor uses its own database to store configured permission policies. If this field is empty, the permission policy will be stored in the `permission_rule` table. Otherwise, it will be stored in the specified database table. If the specified table name does not exist in the database used by Casdoor, it will be created automatically. We strongly recommend **specifying different adapters for different models**, as keeping all policies in the same table may cause conflicts.
+- `Adapter`:
+
+   **Attention!** In the current version, this field describes the name of the database table that stores the permission policy, rather than the name of the adapter configured in the Adapter menu item in the Casdoor Web UI. Casdoor uses its own database to store configured permission policies. If this field is empty, the permission policy will be stored in the `permission_rule` table. Otherwise, it will be stored in the specified database table. If the specified table name does not exist in the database used by Casdoor, it will be created automatically. We strongly recommend **specifying different adapters for different models**, as keeping all policies in the same table may cause conflicts.
 - `Sub users`: Which users will the permission policy be applied to.
-- `Sub roles`: If the RBAC model is used, which roles will be applied to the permission policy. This will add permission policies such as `g user role` for every user in this role.
+- `Sub roles`:
+
+  If the RBAC model is used, which roles will be applied to the permission policy. This will add permission policies such as `g user role` for every user in this role.
 - `Sub domains`: Which domains will the permission policy be applied to.
-- `Resource type`: In the current version, Casdoor does not use this field for external applications that want to authenticate. You can ignore it for now.
-- `Resources`: This field describes the resources for which you wish to enforce permission control. Note, however, that the resources here are not those configured in the Resources menu item of the Casdoor Web UI. You can add any string you want here, such as a URL or a filename.
-- `Actions`: This field describes the actions to operate on resources. Similar to resources, it can be any string you want, such as an HTTP method or other natural language. But please note that Casdoor will convert all these strings to lowercase before storing. Additionally, Casdoor will apply all actions to each resource. You cannot specify that an action only takes effect on certain resources.
-- `Effect`: This option takes effect for Casdoor itself to control application access. If you want an external application to enforce permission controls using the interface Casdoor exposes, it won't do anything. You should describe the effect of pattern matching in the Model file.
+- `Resource type`:
+
+   In the current version, Casdoor does not use this field for external applications that want to authenticate. You can ignore it for now.
+- `Resources`:
+
+  This field describes the resources for which you wish to enforce permission control. Note, however, that the resources here are not those configured in the Resources menu item of the Casdoor Web UI. You can add any string you want here, such as a URL or a filename.
+- `Actions`:
+
+   This field describes the actions to operate on resources. Similar to resources, it can be any string you want, such as an HTTP method or other natural language. But please note that Casdoor will convert all these strings to lowercase before storing. Additionally, Casdoor will apply all actions to each resource. You cannot specify that an action only takes effect on certain resources.
+- `Effect`:
+
+  This option takes effect for Casdoor itself to control application access. If you want an external application to enforce permission controls using the interface Casdoor exposes, it won't do anything. You should describe the effect of pattern matching in the Model file.
 
 As you can see, this configuration page is almost tailor-made for the `(sub, obj, act)` model.

static/img/permission/permission-configuration/.keep

@@ -0,0 +1 @@
+