casdoor · hsluoyz · Jul 10, 2023 · Jul 10, 2023 · Jul 10, 2023
diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml
@@ -1,6 +1,9 @@
 name: Markdown Lint
 
-on: [pull_request]
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
 
 jobs:
   markdownlint:
@@ -19,4 +22,4 @@ jobs:
         run: npm install -g markdownlint-cli
 
       - name: Run markdownlint
-      - run: markdownlint 'docs/**/*.md*' --config .markdownlint.jsonc
+        run: markdownlint 'docs/**/*.{md,mdx}' --config .markdownlint.jsonc
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 The configuration and documentation of Casdoor website: <https://casdoor.org/>.
 
-Casdoor website is built using [Docusaurus](https://docusaurus.io/), you can get the PDF at [casdoor.org/pdf](https://casdoor.org/pdf/) or [GitHub Action](https://github.com/casdoor/casdoor-website/actions/workflows/master.yml).
+Casdoor website is built using [Docusaurus](https://docusaurus.io/), you can get the PDF at [casdoor.org/pdf](https://casdoor.org/pdf) or [GitHub Action](https://github.com/casdoor/casdoor-website/actions/workflows/master.yml).
 
 ## Get Started
 
@@ -53,6 +53,14 @@ content
 
 ````
 
+We use [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) to lint the markdown and mdx files, you can use the following command to fix basic errors and get a list of document issues:
+
+```bash
+yarn lint:md
+```
+
+If you write docs using VSCode, Sublime, or Vim/Neovim, you can install the [extension](https://github.com/DavidAnson/markdownlint#related) to get better lint experience.
+
 #### Caution
 
 ##### Admonitions

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -5,8 +5,6 @@ keywords: [Contributor, guide]
 authors: [leo220yuyaodog]
 ---
 
-# Contributing to Casdoor
-
 Welcome to Casdoor! This document is a guideline about how to contribute to Casdoor.
 
 If you find something incorrect or missing, please leave comments / suggestions.
@@ -88,19 +86,22 @@ The PR title must be in lower case.
 :::
 
 1. **fix**: a commit of the _type_ `fix` patches a bug in your codebase.
-```text
-fix: prevent racing of requests
-```
+
+    ```text
+    fix: prevent racing of requests
+    ```
 
 2. **feat**: a commit of the _type_ `feat` introduces a new feature to the codebase.
-```text
-feat: allow provided config object to extend other configs
-```
+
+    ```text
+    feat: allow provided config object to extend other configs
+    ```
 
 3. **docs**: a commit of the _type_ `docs` add or improve a document.
-```text
-docs: correct spelling of CHANGELOG
-```
+
+    ```text
+    docs: correct spelling of CHANGELOG
+    ```
 
 For more details, please refer to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
 
@@ -112,6 +113,7 @@ pull request is merged.
 #### Linking a pull request to an issue using a keyword
 
 You can link a pull request to an issue by using a supported keyword in the pull request's description or in a commit message. The pull request **must be** on the default branch.
+
 - close
 - fix
 - resolve
@@ -129,36 +131,39 @@ For more details, please see [Link PR to issue](https://docs.github.com/en/issue
 Inevitably, your PR may need to be revised. Please **re-use** the same PR when the code needs changes. Don't close the PR and open a new one.
 
 Here is a possible example:
+
 - Modify the code in your local.
 - Modify this commit.  
+
 ```shell
 git commit --amend
 ```
+
 - Push to your remote repository.  
+
 ```shell
 git push --force
 ```
 
 Then the PR has been modified successfully! You can check it in Casdoor repository.
 
-
-
 ## Code Related
 
 Some principles:
 
 Readability - Important code should be well-documented. Code style should be complied with the existing one.
 
-#### Naming convention
+### Naming convention
 
 e.g.,`signupUrl`for var names,`Signup URL`for UI
 
-#### How to update i18n data?
+### How to update i18n data?
 
 Please note that we use [Crowdin](https://crowdin.com/project/casdoor-site) as translating platform and i18next as
 translating tool. When you add some words using i18next in the `web/` directory, you can run the `i18n/generate_test.go`to auto-generate the `web/src/locales/**/data.json`.
 
 Run `i18n/generate_test.go`:
+
 ```shell
 cd i18n && go test
 ```

diff --git a/docs/how-to-connect/desktop-sdks/dotnet-app.md b/docs/how-to-connect/desktop-sdks/dotnet-app.md
@@ -7,15 +7,15 @@ authors: [zh6335901]
 
 An [Dotnet desktop app example](https://github.com/casdoor/casdoor-dotnet-desktop-example) for Casdoor.
 
-# How to run example
+## How to run example
 
-## Prerequisites
+### Prerequisites
 
 [dotnet6 sdk](https://dotnet.microsoft.com/en-us/download)
 
 [webview2 runtime](https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/#download-section) (It's already preinstalled in your windows generally)
 
-## Initialization
+### Initialization
 
 The initialization requires 5 parameters, which are all string type:
 
@@ -29,19 +29,19 @@ The initialization requires 5 parameters, which are all string type:
 
 If you don't set these parameters, this project will use the [Casdoor online demo](https://door.casdoor.com) as the default Casdoor server and use the [Casnode](https://door.casdoor.com/applications/app-casnode) as the default Casdoor application.
 
-## Running
+### Running
 
-### Visual Studio
+#### Visual Studio
 
 1. Open casdoor-dotnet-desktop-example.sln
 2. Press Ctrl + F5 to start
 
-### Command line
+#### Command line
 
 1. cd src/DesktopApp
 2. dotnet run
 
-## Preview
+### Preview
 
 After you run this dotnet desktop application, a new window will be showed on your desktop.
 ![index](/img/how-to-connect/desktop-sdks/dotnet-app/index.png)
@@ -55,9 +55,9 @@ After you login successfully, a user profile window will be showed on your deskt
 You can preview the whole process by the gif image below.
 ![preview gif](/img/how-to-connect/desktop-sdks/dotnet-app/preview.gif)
 
-# How to integrate
+## How to integrate
 
-## Open the login window
+### Open the login window
 
 ```csharp
 var login = new Login();
@@ -66,7 +66,7 @@ login.CodeReceived += Login_CodeReceived;
 login.ShowDialog();
 ```
 
-## Use auth code to get the user info
+### Use auth code to get the user info
 
 ```csharp
 public async Task<string?> RequestToken(string clientId, string clientSecret, string code)

diff --git a/docs/how-to-connect/desktop-sdks/electron-app.md b/docs/how-to-connect/desktop-sdks/electron-app.md
@@ -36,7 +36,7 @@ Builds the electron app and run this app.
 
 Package and distribute your application. It will create the `out` folder where your package will be located:
 
-```
+```bash
 // Example for macOS out/  
 ├── out/make/zip/darwin/x64/casdoor-electron-example-darwin-x64-1.0.0.zip  
 ├── ...  

diff --git a/docs/how-to-connect/overview.md b/docs/how-to-connect/overview.md
@@ -68,7 +68,7 @@ provide the best **flexibility** and the most **powerful** API.
 
 **plugin:**
 
-- [Jenkins plugin](/docs/integration/java/jenkins%20plugin)
+- [Jenkins plugin](/docs/integration/java/jenkins-plugin)
 - [APISIX plugin](/docs/integration/lua/apisix#connect-casdoor-via-apisixs-casdoor-plugin)
 
 **Middleware:**

diff --git a/docs/how-to-connect/saml/google-workspace.md b/docs/how-to-connect/saml/google-workspace.md
@@ -11,48 +11,49 @@ authors: [UsherFall]
 
 This guide will show you how to configure Casdoor and Google Workspace to add Casdoor as a SAML IdP in Google Workspace
 
-### Add Certificate 
+### Add Certificate
 
 In Casdoor, add a certificate of type X.509 with RSA crypto algorithm and download it.
 
-![](/img/how-to-connect/saml/saml_google-workspace_cert.png)
+![Add cert](/img/how-to-connect/saml/saml_google-workspace_cert.png)
 
 ### Configure SAML Application
 
 In the application edit page, select the certificate you just created. Add the domain name of the Google application you will use in the **Redirect URLs**, such as google.com.
 
-![](/img/how-to-connect/saml/saml_google-workspace_app.png)
+![Select cert and add redirect URLs](/img/how-to-connect/saml/saml_google-workspace_app.png)
 
 In the **SAML reply URL** field, enter`https://www.google.com/a/<your domain>/acs`, which is the ACS URL. You can find relevant information about ACS URL here: [SSO assertion requirements](https://support.google.com/a/answer/6330801)
 
-![](/img/how-to-connect/saml/saml_google-workspace_acs.png)
+![Enter the SAML reply URL field](/img/how-to-connect/saml/saml_google-workspace_acs.png)
 
-Copy the **sigin page URL**. This will be used in the next step.
+Copy the **signin page URL**. This will be used in the next step.
 
-![](/img/how-to-connect/saml/saml_google-workspace_login.png)
+![Copy the signin page URL](/img/how-to-connect/saml/saml_google-workspace_login.png)
 
 ### Add Third-Party SAML IdP for Google Workspace
 
-In the Google Workspace Admin console, navigate to **Security** and then **Overview**. Look for the **SSO with third-party Idp** section. 
+In the Google Workspace Admin console, navigate to **Security** and then **Overview**. Look for the **SSO with third-party Idp** section.
 Click on Add SSO profile to access the editing page. Check the Set up SSO with third-party identity provider checkbox. Paste the copied sigin page URL into the **Sign-in page URL** and **Sign-out page URL** fields. Upload the certificate downloaded in the previous step. Click Save to save the changes.
 
-![](/img/how-to-connect/saml/saml_google-workspace_conf.png)
+![Configure Google Workspace](/img/how-to-connect/saml/saml_google-workspace_conf.png)
 
 ### Add Users for Testing
 
 In Google Workspace, create a user with the username "test" (you can customize the username, this is just an example).
 
-![](/img/how-to-connect/saml/saml_google-workspace_user.png)
+![Add a user in Google Workspace](/img/how-to-connect/saml/saml_google-workspace_user.png)
 
 In Casdoor, add a user with the same username as set in Google Workspace. Make sure to select the appropriate organization and enter the user's email address.
 
-![](/img/how-to-connect/saml/saml_google-workspace_test.png)
+![Add a user in Casdoor](/img/how-to-connect/saml/saml_google-workspace_test.png)
 
 As an example using "google.com," follow these steps:
+
 1. Click on the login button on the Google.com page.
 Enter the user's email address to initiate the login process.
 2. You will be redirected to the Casdoor page.
 On the Casdoor page, enter the corresponding email address and password.
 3. If the login is successful, you will be redirected back to google.com
 
-![](/img/how-to-connect/saml/saml_google-workspace_test_gif.gif)
+![Final result](/img/how-to-connect/saml/saml_google-workspace_test_gif.gif)
diff --git a/docs/how-to-connect/saml/keycloak.md b/docs/how-to-connect/saml/keycloak.md
@@ -23,7 +23,7 @@ You can visit Keycloak SAML Identity Providers [documentation](https://www.keycl
 
 :::
 
-Enter the **Alias** and the **Import from URL** in Keycloak IdP edit page. The content of **Import from URL** can be found in the Casdoor application edit page. Click **Import** and the SAML config will be filled automatically. 
+Enter the **Alias** and the **Import from URL** in Keycloak IdP edit page. The content of **Import from URL** can be found in the Casdoor application edit page. Click **Import** and the SAML config will be filled automatically.
 
 ![saml_keycloak_idp_edit](/img/how-to-connect/saml/saml_keycloak_idp_edit.png)
 
@@ -37,7 +37,7 @@ In the application edit page, add a redirect URL which the content of it is **Se
 
 ### Login using Casdoor SAML
 
-Open the Keycloak login page and you can find the additional button that allows you to login to Keycloak using the Casdoor SAML provider. 
+Open the Keycloak login page and you can find the additional button that allows you to login to Keycloak using the Casdoor SAML provider.
 
 ![saml_keycloak_login](/img/how-to-connect/saml/saml_keycloak_login.png)
 

diff --git a/docs/how-to-connect/saml/overview.md b/docs/how-to-connect/saml/overview.md
@@ -37,14 +37,14 @@ The `Reply URL` will overwrites the `AssertionConsumerServiceURL` in `SAMLReques
 
   ![Reply URL](/img/how-to-connect/saml/saml_replyURL.png)
 
-- **Redirect URL** Type in a unique name. This may be called `Audience` or `Entity ID` in your SP. Make sure you fill the 
+- **Redirect URL** Type in a unique name. This may be called `Audience` or `Entity ID` in your SP. Make sure you fill the
   same `Redirect URL` here as in your SP.
 
   ![Entity ID](/img/how-to-connect/saml/saml_entityId.png)
 
 ### User profile
 
-After logged in successfully, the user profile in the `SAMLResponse` Casdoor returned has three fields. The attributes in 
+After logged in successfully, the user profile in the `SAMLResponse` Casdoor returned has three fields. The attributes in
 the xml and the attributes of the user in casdoor are mapped as follows:
 
 | XML Attribute Name |  User field   |
@@ -191,7 +191,7 @@ func main() {
 
 Run the above codes and the console will display the following message.
 
-```
+```text
 Visit this URL To Authenticate:
 http://localhost:7001/login/saml/authorize/admin/app-built-in?SAMLRequest=lFVbk6K8Fv0rFvNo2QR...
 Supply:

diff --git a/docs/integration/Haskell/Hasura.md b/docs/integration/Haskell/Hasura.md
@@ -33,6 +33,7 @@ Choose a password for your user and confirm it.
 Start the Hasura by docker or Hasura Cloud.
 
 Now create a `users` table with the following columns:
+
 * `id` of type Text (Primary Key)
 * `username` of type Text
 
@@ -62,7 +63,7 @@ To do so, go to the Hasura docker-compose.yaml and then add the new `HASURA_GRAP
 
 The `HASURA_GRAPHQL_JWT_SECRET` should be in the following format:
 
-```
+```yaml
 HASURA_GRAPHQL_JWT_SECRET: '{"claims_map": {
       "x-hasura-allowed-roles": ["user","editor"],
       "x-hasura-default-role": "user",
@@ -77,7 +78,8 @@ Save the change, and reload the docker.
 ## Retrieve JWT Token
 
 Since there is no client implementation, you can get your access token by making a request by below URL:
-```
+
+```url
 http://localhost:8000/login/oauth/authorize?client_id=<client ID>>&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flogin&scope=read&state=app-built-in<public certificate>>
 ```
 
@@ -101,4 +103,4 @@ Copy the Access Token.
 
 Now you can use the access token to make the authenticated request. Hasura returned the appropriate user rather than returning all the users from the database.
 
-![Picture showing the access token from Keycloak being used in Hasura](/img/integration/Haskell/Hasura/hasura.png)
+![Picture showing the access token from Keycloak being used in Hasura](/img/integration/Haskell/Hasura/hasura.png)
diff --git a/docs/integration/go/bookstack.md b/docs/integration/go/bookstack.md
@@ -19,7 +19,7 @@ Go to your Casdoor and add your new application **BookStack**. Here is an **exam
 ![bookstack_config.png](/img/integration/go/bookstack/config.png)
 Please remember the `Name`, `Organization`, `client ID`, and `client Secret`. You will use them in the next step.
 
-### Step2. Configure Casdoor Login 
+### Step2. Configure Casdoor Login
 
 Now, please move to the BookStack.  Find the file: `oauth.conf.example`.
 
@@ -46,4 +46,3 @@ Make sure the `Redirect URL` is the same as the `redirectUrl` in the file `oauth
 **Now that you've done all the configuration for Casdoor!**
 
 You can go back to your BookStack and experience using Casdoor for login authentication once the BookStack has been successfully deployed.
-