Merge pull request #6113 from logto-io/gao-upgrade-mdx

refactor(console): upgrade mdx packages

Author: gao-sun

packages/console/.parcelrc

@@ -6,7 +6,7 @@
       "@parcel/transformer-svg-react"
     ],
     "*.{md,mdx}": [
-      "@parcel/transformer-mdx"
+      "./parcel-transformer-mdx2.js"
     ]
   },
   "compressors": {

packages/console/.parcelrc.arm64

@@ -10,7 +10,7 @@
       "@parcel/transformer-svg-react"
     ],
     "*.{md,mdx}": [
-      "@parcel/transformer-mdx"
+      "./parcel-transformer-mdx2.js"
     ]
   },
   "compressors": {

packages/console/package.json

@@ -36,12 +36,12 @@
     "@logto/react": "^3.0.8",
     "@logto/schemas": "workspace:^1.17.0",
     "@logto/shared": "workspace:^3.1.1",
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/mdx": "^3.0.1",
+    "@mdx-js/react": "^3.0.1",
     "@monaco-editor/react": "^4.6.0",
     "@parcel/compressor-brotli": "2.9.3",
     "@parcel/compressor-gzip": "2.9.3",
     "@parcel/core": "2.9.3",
-    "@parcel/transformer-mdx": "2.9.3",
     "@parcel/transformer-sass": "2.9.3",
     "@parcel/transformer-svg-react": "2.9.3",
     "@silverhand/eslint-config": "6.0.1",
@@ -55,8 +55,7 @@
     "@types/color": "^3.0.3",
     "@types/debug": "^4.1.7",
     "@types/jest": "^29.4.0",
-    "@types/mdx": "^2.0.1",
-    "@types/mdx-js__react": "^1.5.5",
+    "@types/mdx": "^2.0.13",
     "@types/react": "^18.0.31",
     "@types/react-color": "^3.0.6",
     "@types/react-dom": "^18.0.0",
@@ -88,6 +87,7 @@
     "ky": "^1.2.3",
     "libphonenumber-js": "^1.10.51",
     "lint-staged": "^15.0.0",
+    "mermaid": "^10.9.1",
     "nanoid": "^5.0.1",
     "overlayscrollbars": "^2.0.2",
     "overlayscrollbars-react": "^0.5.0",

packages/console/parcel-transformer-mdx2.js

@@ -0,0 +1,57 @@
+// https://github.com/parcel-bundler/parcel/pull/7922#issuecomment-1750704973
+
+import { compile } from '@mdx-js/mdx';
+import { default as ThrowableDiagnostic } from '@parcel/diagnostic';
+import { Transformer } from '@parcel/plugin';
+
+export default new Transformer({
+  async transform({ asset }) {
+    const source = await asset.getCode();
+
+    let codeVFile;
+
+    try {
+      codeVFile = await compile(source, {
+        development: true,
+        jsx: true,
+        providerImportSource: '@mdx-js/react',
+      });
+    } catch (error) {
+      const { start, end } = error.position;
+
+      const highlight = {
+        message: error.reason,
+        start,
+        end,
+      };
+
+      if (!(end.line && end.column)) {
+        highlight.end = { ...start };
+      }
+
+      // Adjust for parser and reporter differences
+      highlight.start.column -= 1;
+      highlight.end.column -= 1;
+
+      throw new ThrowableDiagnostic({
+        diagnostic: {
+          message: 'Unable to compile MDX',
+          codeFrames: [
+            {
+              filePath: asset.filePath,
+              code: source,
+              codeHighlights: [highlight],
+            },
+          ],
+        },
+      });
+    }
+
+    const code = String(codeVFile);
+
+    asset.type = 'jsx';
+    asset.setCode(code);
+
+    return [asset];
+  },
+});

packages/console/src/assets/docs/guides/api-express/README.mdx

@@ -28,8 +28,7 @@ To proceed, you'll need to integrate the Logto SDK into your client application.
 
 You'll also need to tweak the Logto SDK configuration to inform Logto that you want to request an access token for your API in this grant. Here's an example using React:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`import { LogtoProvider } from '@logto/react';
 
 const App = () => {
@@ -44,27 +43,23 @@ const App = () => {
     </LogtoProvider>
   );
 };`}
-  </code>
-</pre>
+</Code>
 
 Once a user signs in with Logto, `isAuthenticated` within the Logto SDK will become `true`:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`import { useLogto } from '@logto/react';
 
 const Content = () => {
   const { isAuthenticated } = useLogto();
 
   console.log(isAuthenticated); // true
 };`}
-  </code>
-</pre>
+</Code>
 
 Now, you can use the `getAccessToken` method to retrieve an access token for your API:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`const Content = () => {
   const { getAccessToken, isAuthenticated } = useLogto();
 
@@ -75,13 +70,11 @@ Now, you can use the `getAccessToken` method to retrieve an access token for you
     }
   }, [isAuthenticated, getAccessToken]);
 };`}
-  </code>
-</pre>
+</Code>
 
 Lastly, include this access token in the `Authorization` header when making requests to your API:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`const Content = () => {
   const { getAccessToken, isAuthenticated } = useLogto();
 
@@ -97,8 +90,7 @@ Lastly, include this access token in the `Authorization` header when making requ
     }
   }, [isAuthenticated, getAccessToken]);
 };`}
-  </code>
-</pre>
+</Code>
 
 </Step>
 
@@ -150,8 +142,7 @@ const extractBearerTokenFromHeaders = ({ authorization }: IncomingHttpHeaders) =
 
 Subsequently, create a middleware to verify the access token:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`import { createRemoteJWKSet, jwtVerify } from 'jose';
 
 // Generate a JWKS using jwks_uri obtained from the Logto server
@@ -181,8 +172,7 @@ export const authMiddleware = async (req, res, next) => {
 
   return next();
 };`}
-  </code>
-</pre>
+</Code>
 
 You can now employ this middleware to protect your API endpoints:
 
@@ -210,17 +200,15 @@ To address this, we can employ role-based access control (RBAC). In Logto, you c
 
 After defining roles and permissions, you can add the `scopes` option to the `LogtoProvider` component:
 
-<pre>
-  <code className="language-ts">
+<Code className="language-ts">
   {`<LogtoProvider
   config={{
     // ...other configurations
     resources: ['${props.audience}'],
     scopes: ['read:products', 'write:products'], // Replace with the actual scope(s)
   }}
 >`}
-  </code>
-</pre>
+</Code>
 
 Logto will then only issue an access token with the appropriate scope(s) to the user. For instance, if a user only has the `read:products` scope, the access token will solely contain that scope:
 

packages/console/src/assets/docs/guides/api-python/README.mdx

@@ -48,19 +48,16 @@ All the latest public Logto Authorization Configurations can be found at <code>{
 e.g. You can locate the following two fields in the response body if you request the above endpoint.
 </p>
 
-<pre>
-  <code className="language-json">
+<Code className="language-json">
 {`{
   "issuer": "${appendPath(props.endpoint, '/oidc')}",
   "jwks_uri": "${appendPath(props.endpoint, '/oidc/jwks')}"
 }`}
-  </code>
-</pre>
+</Code>
 
 ### Create the authorization validation decorator
 
-<pre>
-  <code className="language-python">
+<Code className="language-python">
 {`"""requires-auth.py
 """
 
@@ -105,8 +102,7 @@ def requires_auth(f):
 
     return f(*args, **kwargs)
   return decorated`}
-  </code>
-</pre>
+</Code>
 
 <InlineNotification>
   For <a href="https://docs.logto.io/docs/recipes/rbac/" target="_blank" rel="noopener">🔐 RBAC</a>, scope validation is also required.

packages/console/src/assets/docs/guides/api-spring-boot/README.mdx

@@ -59,25 +59,22 @@ Before moving on, you will need to get an issuer and a JWKS URI to verify the is
 
 An example of the response:
 
-<pre>
-  <code className="language-json">
+<Code className="language-json">
     {`{
   // ...
   "issuer": "${appendPath(props.endpoint, '/oidc')}",
   "jwks_uri": "${appendPath(props.endpoint, '/oidc/jwks')}"
   // ...
 }`}
-  </code>
-</pre>
+</Code>
 
 </Step>
 
 <Step title="Configure application">
 
 Use an `application.yml` file (instead of the default `application.properties`) to configure the server port, audience, and OAuth2 resource server.
 
-<pre>
-  <code className="language-yaml">
+<Code className="language-yaml">
     {`# path/to/project/src/main/resources/application.yaml
 server:
   port: 3000
@@ -92,8 +89,7 @@ spring:
         jwt:
           issuer-uri: ${appendPath(props.endpoint, '/oidc')}
           jwk-set-uri: ${appendPath(props.endpoint, '/oidc/jwks')}`}
-  </code>
-</pre>
+</Code>
 
 - `audience`: The unique API identifier of your protected API resource.
 - `spring.security.oauth2.resourceserver.jwt.issuer-uri`: The iss claim value and the issuer URI in the JWT issued by Logto.
@@ -277,12 +273,10 @@ gradlew.bat bootRun
 
 Request your protected API with the Access Token as the Bearer token in the Authorization header, e.g. execute the `curl` command.
 
-<pre>
-  <code className="language-bash">
+<Code className="language-bash">
     {`curl --include '${appendPath(props.endpoint, '/api/profile')}' \\
 --header 'Authorization: Bearer <your-access-token>'`}
-  </code>
-</pre>
+</Code>
 
 If successful, you will get a response with 200 status:
 

packages/console/src/assets/docs/guides/native-android/README.mdx

@@ -55,8 +55,7 @@ Since the SDK needs internet access, you need to add the following permission to
 
 Create a `LogtoViewModel.kt` and init `LogtoClient` in this view model:
 
-<pre>
-  <code className="language-kotlin">
+<Code className="language-kotlin">
     {`//...with other imports
 import io.logto.sdk.android.LogtoClient
 import io.logto.sdk.android.type.LogtoConfig
@@ -86,8 +85,7 @@ class LogtoViewModel(application: Application) : AndroidViewModel(application) {
         }
     }
 }`}
-  </code>
-</pre>
+</Code>
 
 then, create a `LogtoViewModel` for your `MainActivity.kt`:
 
@@ -121,8 +119,7 @@ You can add the redirect URI in the following input field:
 
 After the redirect URI is configured, we add a `signIn` method to your `LogtoViewModel.kt`, which will call `logtoClient.signIn` API to invoke the Logto sign-in page:
 
-<pre>
-  <code className="language-kotlin">
+<Code className="language-kotlin">
     {`//...with other imports
 class LogtoViewModel(application: Application) : AndroidViewModel(application) {
     // ...other codes
@@ -132,8 +129,7 @@ class LogtoViewModel(application: Application) : AndroidViewModel(application) {
         }
     }
 }`}
-  </code>
-</pre>
+</Code>
 
 Now setup on-click listener for the sign-in button in your `MainActivity.kt` to call the `signIn` method:
 
@@ -205,8 +201,7 @@ In Logto SDK, we can use `logtoClient.isAuthenticated` to check the authenticati
 
 Now, let's add a live data to `LogtoViewModel.kt` to observe the authentication status, and update the status when the user signed in or signed out:
 
-<pre>
-  <code className="language-kotlin">
+<Code className="language-kotlin">
     {`//...with other imports
 class LogtoViewModel(application: Application) : AndroidViewModel(application) {
     // ...other codes
@@ -232,8 +227,7 @@ class LogtoViewModel(application: Application) : AndroidViewModel(application) {
         }
     }
 }`}
-  </code>
-</pre>
+</Code>
 
 Then, we observe the `authenticated` live data in `MainActivity.kt`, when the user is signed in, we hide the sign-in button and show the sign-out button and vice versa: