From 8fcb747032f7c7d1cc8fdaa49294c51bc1d0f2e0 Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Wed, 26 Jun 2024 16:32:45 +0800 Subject: [PATCH] refactor(console): upgrade mdx packages --- packages/console/.parcelrc | 2 +- packages/console/.parcelrc.arm64 | 2 +- packages/console/package.json | 8 +- packages/console/parcel-transformer-mdx2.js | 57 + .../assets/docs/guides/api-express/README.mdx | 36 +- .../assets/docs/guides/api-python/README.mdx | 12 +- .../docs/guides/api-spring-boot/README.mdx | 18 +- .../docs/guides/native-android/README.mdx | 18 +- .../docs/guides/native-capacitor/README.mdx | 18 +- .../assets/docs/guides/native-expo/README.mdx | 18 +- .../docs/guides/native-flutter/README.mdx | 18 +- .../docs/guides/native-ios-swift/README.mdx | 12 +- .../assets/docs/guides/spa-angular/README.mdx | 6 +- .../assets/docs/guides/spa-react/README.mdx | 18 +- .../assets/docs/guides/spa-vanilla/README.mdx | 18 +- .../src/assets/docs/guides/spa-vue/README.mdx | 6 +- .../assets/docs/guides/spa-webflow/README.mdx | 18 +- .../web-dotnet-core-blazor-server/README.mdx | 6 +- .../web-dotnet-core-blazor-wasm/README.mdx | 6 +- .../guides/web-dotnet-core-mvc/README.mdx | 6 +- .../docs/guides/web-dotnet-core/README.mdx | 6 +- .../assets/docs/guides/web-express/README.mdx | 12 +- .../src/assets/docs/guides/web-go/README.mdx | 18 +- .../guides/web-java-spring-boot/README.mdx | 6 +- .../guides/web-next-app-router/README.mdx | 8 +- .../docs/guides/web-next-auth/README.mdx | 6 +- .../assets/docs/guides/web-next/README.mdx | 6 +- .../assets/docs/guides/web-nuxt/README.mdx | 16 +- .../src/assets/docs/guides/web-php/README.mdx | 24 +- .../assets/docs/guides/web-python/README.mdx | 30 +- .../assets/docs/guides/web-remix/README.mdx | 12 +- .../assets/docs/guides/web-ruby/README.mdx | 30 +- .../docs/guides/web-sveltekit/README.mdx | 18 +- .../console/src/components/Guide/index.tsx | 34 +- .../console/src/mdx-components/Code/index.tsx | 24 + .../src/mdx-components/MdxProvider/index.tsx | 33 + .../src/mdx-components/Mermaid/index.tsx | 82 + .../EnterpriseSsoDetails/SsoGuide/index.tsx | 15 +- pnpm-lock.yaml | 1728 +++++++++++------ 39 files changed, 1521 insertions(+), 890 deletions(-) create mode 100644 packages/console/parcel-transformer-mdx2.js create mode 100644 packages/console/src/mdx-components/Code/index.tsx create mode 100644 packages/console/src/mdx-components/MdxProvider/index.tsx create mode 100644 packages/console/src/mdx-components/Mermaid/index.tsx diff --git a/packages/console/.parcelrc b/packages/console/.parcelrc index bdafd2c2b..eeade8d28 100644 --- a/packages/console/.parcelrc +++ b/packages/console/.parcelrc @@ -6,7 +6,7 @@ "@parcel/transformer-svg-react" ], "*.{md,mdx}": [ - "@parcel/transformer-mdx" + "./parcel-transformer-mdx2.js" ] }, "compressors": { diff --git a/packages/console/.parcelrc.arm64 b/packages/console/.parcelrc.arm64 index 0bc273f89..c31f639e1 100644 --- a/packages/console/.parcelrc.arm64 +++ b/packages/console/.parcelrc.arm64 @@ -10,7 +10,7 @@ "@parcel/transformer-svg-react" ], "*.{md,mdx}": [ - "@parcel/transformer-mdx" + "./parcel-transformer-mdx2.js" ] }, "compressors": { diff --git a/packages/console/package.json b/packages/console/package.json index 02627ef31..ca2e8b905 100644 --- a/packages/console/package.json +++ b/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", diff --git a/packages/console/parcel-transformer-mdx2.js b/packages/console/parcel-transformer-mdx2.js new file mode 100644 index 000000000..367247041 --- /dev/null +++ b/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]; + }, +}); diff --git a/packages/console/src/assets/docs/guides/api-express/README.mdx b/packages/console/src/assets/docs/guides/api-express/README.mdx index 7c0b04da8..9621af201 100644 --- a/packages/console/src/assets/docs/guides/api-express/README.mdx +++ b/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: -
-  
+
   {`import { LogtoProvider } from '@logto/react';
 
 const App = () => {
@@ -44,13 +43,11 @@ const App = () => {
     
   );
 };`}
-  
-
+ Once a user signs in with Logto, `isAuthenticated` within the Logto SDK will become `true`: -
-  
+
   {`import { useLogto } from '@logto/react';
 
 const Content = () => {
@@ -58,13 +55,11 @@ const Content = () => {
 
   console.log(isAuthenticated); // true
 };`}
-  
-
+ Now, you can use the `getAccessToken` method to retrieve an access token for your API: -
-  
+
   {`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]);
 };`}
-  
-
+ Lastly, include this access token in the `Authorization` header when making requests to your API: -
-  
+
   {`const Content = () => {
   const { getAccessToken, isAuthenticated } = useLogto();
 
@@ -97,8 +90,7 @@ Lastly, include this access token in the `Authorization` header when making requ
     }
   }, [isAuthenticated, getAccessToken]);
 };`}
-  
-
+ @@ -150,8 +142,7 @@ const extractBearerTokenFromHeaders = ({ authorization }: IncomingHttpHeaders) = Subsequently, create a middleware to verify the access token: -
-  
+
   {`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();
 };`}
-  
-
+ You can now employ this middleware to protect your API endpoints: @@ -210,8 +200,7 @@ 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: -
-  
+
   {``}
-  
-
+ 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: diff --git a/packages/console/src/assets/docs/guides/api-python/README.mdx b/packages/console/src/assets/docs/guides/api-python/README.mdx index 621abc927..313af49f7 100644 --- a/packages/console/src/assets/docs/guides/api-python/README.mdx +++ b/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 { e.g. You can locate the following two fields in the response body if you request the above endpoint.

-
-  
+
 {`{
   "issuer": "${appendPath(props.endpoint, '/oidc')}",
   "jwks_uri": "${appendPath(props.endpoint, '/oidc/jwks')}"
 }`}
-  
-
+ ### Create the authorization validation decorator -
-  
+
 {`"""requires-auth.py
 """
 
@@ -105,8 +102,7 @@ def requires_auth(f):
 
     return f(*args, **kwargs)
   return decorated`}
-  
-
+ For 🔐 RBAC, scope validation is also required. diff --git a/packages/console/src/assets/docs/guides/api-spring-boot/README.mdx b/packages/console/src/assets/docs/guides/api-spring-boot/README.mdx index 609441c5e..16bbfb725 100644 --- a/packages/console/src/assets/docs/guides/api-spring-boot/README.mdx +++ b/packages/console/src/assets/docs/guides/api-spring-boot/README.mdx @@ -59,16 +59,14 @@ Before moving on, you will need to get an issuer and a JWKS URI to verify the is An example of the response: -
-  
+
     {`{
   // ...
   "issuer": "${appendPath(props.endpoint, '/oidc')}",
   "jwks_uri": "${appendPath(props.endpoint, '/oidc/jwks')}"
   // ...
 }`}
-  
-
+ @@ -76,8 +74,7 @@ An example of the response: Use an `application.yml` file (instead of the default `application.properties`) to configure the server port, audience, and OAuth2 resource server. -
-  
+
     {`# 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')}`}
-  
-
+ - `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. -
-  
+
     {`curl --include '${appendPath(props.endpoint, '/api/profile')}' \\
 --header 'Authorization: Bearer '`}
-  
-
+ If successful, you will get a response with 200 status: diff --git a/packages/console/src/assets/docs/guides/native-android/README.mdx b/packages/console/src/assets/docs/guides/native-android/README.mdx index b6a966f56..9bf1c49f2 100644 --- a/packages/console/src/assets/docs/guides/native-android/README.mdx +++ b/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: -
-  
+
     {`//...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) {
         }
     }
 }`}
-  
-
+ 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: -
-  
+
     {`//...with other imports
 class LogtoViewModel(application: Application) : AndroidViewModel(application) {
     // ...other codes
@@ -132,8 +129,7 @@ class LogtoViewModel(application: Application) : AndroidViewModel(application) {
         }
     }
 }`}
-  
-
+ 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: -
-  
+
     {`//...with other imports
 class LogtoViewModel(application: Application) : AndroidViewModel(application) {
     // ...other codes
@@ -232,8 +227,7 @@ class LogtoViewModel(application: Application) : AndroidViewModel(application) {
         }
     }
 }`}
-  
-
+ 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: diff --git a/packages/console/src/assets/docs/guides/native-capacitor/README.mdx b/packages/console/src/assets/docs/guides/native-capacitor/README.mdx index ab26eae2e..a0e5c8e6a 100644 --- a/packages/console/src/assets/docs/guides/native-capacitor/README.mdx +++ b/packages/console/src/assets/docs/guides/native-capacitor/README.mdx @@ -27,16 +27,14 @@ npm install @capacitor/browser @capacitor/app @capacitor/preferences Add the following code to your Capacitor project: -
-  
+
     {`import LogtoClient from '@logto/capacitor';
 
 const logtoClient = new LogtoClient({
   endpoint: '${props.endpoint}',
   appId: '${props.app.id}',
 });`}
-  
-
+ @@ -50,15 +48,13 @@ Ensure that the URI redirects to the Capacitor app, for example, `com.example.ap Remember to click on **Save changes** after updating the redirect URI. Then, add the following code to the `onClick` handler of the sign-in button: -
-  
+
     {`const onClick = async () => {
   await logtoClient.signIn('${props.redirectUris[0] || 'com.example.app://callback'}');
   console.log(await logtoClient.isAuthenticated()); // true
   console.log(await logtoClient.getIdTokenClaims()); // { sub: '...', ... }
 };`}
-  
-
+ @@ -108,13 +104,11 @@ The user needs to click "Done" to close the web view and return to the Capacitor Ensure that the post sign-out redirect URI redirects to the Capacitor app. Then add the following code to the `onClick` handler of the sign-out button: -
-  
+
     {`const onClick = async () => {
   await logtoClient.signOut('${props.postLogoutRedirectUris[0] || 'com.example.app://callback/sign-out'}');
 };`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/native-expo/README.mdx b/packages/console/src/assets/docs/guides/native-expo/README.mdx index 8cb488101..6d553853c 100644 --- a/packages/console/src/assets/docs/guides/native-expo/README.mdx +++ b/packages/console/src/assets/docs/guides/native-expo/README.mdx @@ -56,8 +56,7 @@ If you're installing this in a [bare React Native app](https://docs.expo.dev/bar Import and use `LogtoProvider` to provide a Logto context: -
-  
+
     {`import { LogtoProvider, LogtoConfig } from '@logto/rn';
 
 const config: LogtoConfig = {
@@ -70,8 +69,7 @@ const App = () => (
     
   
 );`}
-  
-
+ @@ -100,8 +98,7 @@ The redirect URI is used to redirect the user back to your app after they sign i You can use `useLogto` hook to sign in and sign out: -
-  
+
     {`import { useLogto } from '@logto/rn';
 import { Button } from 'react-native';
 
@@ -120,8 +117,7 @@ const Content = () => {
     
   );
 };`}
-  
-
+ @@ -129,8 +125,7 @@ const Content = () => { To display the user's information, you can use the `getIdTokenClaims()` method: -
-  
+
     {`import { useLogto } from '@logto/rn';
 import { Button, Text } from 'react-native';
 
@@ -162,8 +157,7 @@ const Content = () => {
     
   );
 };`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/native-flutter/README.mdx b/packages/console/src/assets/docs/guides/native-flutter/README.mdx index c192872ef..8abd349a3 100644 --- a/packages/console/src/assets/docs/guides/native-flutter/README.mdx +++ b/packages/console/src/assets/docs/guides/native-flutter/README.mdx @@ -154,8 +154,7 @@ In order to capture the callback url from Logto's sign-in web page, you will nee Import the `logto_dart_sdk` package and initialize the `LogtoClient` instance at the root of your application. -
-  
+
     {`
 import 'package:logto_dart_sdk/logto_dart_sdk.dart';
 import 'package:http/http.dart' as http;
@@ -175,8 +174,7 @@ void init() async {
   );
 }
 `}
-  
-
+ @@ -193,14 +191,12 @@ Let's switch to the Application details page of Logto Admin Console. Add a Redir ### Implement a sign-in method -
-  
+
     {`void signIn() async {
   await logtoClient.signIn('${props.redirectUris[0] ?? 'io.logto://callback'}');
 }
   `}
-  
-
+ @@ -235,8 +231,7 @@ user is signed in, the value will be `true`, otherwise, the value will be `false Now let's wrap up the implementation and test your application. -
-  
+
     {`import 'package:logto_dart_sdk/logto_dart_sdk.dart';
 import 'package:http/http.dart' as http;
 
@@ -330,8 +325,7 @@ class _MyHomePageState extends State {
   }
 }
 `}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/native-ios-swift/README.mdx b/packages/console/src/assets/docs/guides/native-ios-swift/README.mdx index 67cf5da0f..6bdfc3cef 100644 --- a/packages/console/src/assets/docs/guides/native-ios-swift/README.mdx +++ b/packages/console/src/assets/docs/guides/native-ios-swift/README.mdx @@ -44,8 +44,7 @@ CocoaPods [does not support local dependency](https://github.com/CocoaPods/Cocoa subtitle="1 step" > -
-  
+
     {`import Logto
 import LogtoClient
 
@@ -54,8 +53,7 @@ let config = try? LogtoConfig(
   appId: "${props.app.id}"
 )
 let logtoClient = LogtoClient(useConfig: config)`}
-  
-
+ By default, we store credentials like ID Token and Refresh Token in Keychain. Thus the user doesn't need to sign in again when he returns. @@ -91,8 +89,7 @@ First, let’s configure your redirect URI scheme. E.g. `io.logto://callback` Go back to Xcode, use the following code to implement sign-in: -
-  
+
     {`do {
   try await client.signInWithBrowser(redirectUri: "${
     props.redirectUris[0] ?? 'io.logto://callback'
@@ -101,8 +98,7 @@ Go back to Xcode, use the following code to implement sign-in:
 } catch let error as LogtoClientErrors.SignIn {
   // error occured during sign in
 }`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/spa-angular/README.mdx b/packages/console/src/assets/docs/guides/spa-angular/README.mdx index 095f3e086..fd7f2d05c 100644 --- a/packages/console/src/assets/docs/guides/spa-angular/README.mdx +++ b/packages/console/src/assets/docs/guides/spa-angular/README.mdx @@ -58,8 +58,7 @@ After signing out, it'll be great to redirect user back to your website. For exa Back to your Angular project, add the auth provider your `app.config.ts`: -
-  
+
     {`import { UserScope, buildAngularAuthConfig } from '@logto/js';
 import { provideAuth } from 'angular-auth-oidc-client';
 
@@ -77,8 +76,7 @@ export const appConfig: ApplicationConfig = {
     // ...other providers
   ],
 };`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/spa-react/README.mdx b/packages/console/src/assets/docs/guides/spa-react/README.mdx index 8f684b45e..67bd12a9f 100644 --- a/packages/console/src/assets/docs/guides/spa-react/README.mdx +++ b/packages/console/src/assets/docs/guides/spa-react/README.mdx @@ -40,8 +40,7 @@ pnpm add @logto/react Import and use `LogtoProvider` to provide a Logto context: -
-  
+
     {`import { LogtoProvider, LogtoConfig } from '@logto/react';
 
 const config: LogtoConfig = {
@@ -54,8 +53,7 @@ const App = () => (
     
   
 );`}
-  
-
+ @@ -80,8 +78,7 @@ We provide two hooks `useHandleSignInCallback()` and `useLogto()` which can help Go back to your IDE/editor, use the following code to implement the sign-in button: -
-  
+
     {`import { useLogto } from '@logto/react';
 
 const SignIn = () => {
@@ -97,8 +94,7 @@ const SignIn = () => {
     
   );
 };`}
-  
-
+ ### Handle redirect @@ -140,8 +136,7 @@ After signing out, it'll be great to redirect user back to your website. Let's a ### Implement a sign-out button -
-  
+
     {`const SignOut = () => {
   const { signOut } = useLogto();
 
@@ -153,8 +148,7 @@ After signing out, it'll be great to redirect user back to your website. Let's a
     
   );
 };`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/spa-vanilla/README.mdx b/packages/console/src/assets/docs/guides/spa-vanilla/README.mdx index d0848d2b2..eab0facc9 100644 --- a/packages/console/src/assets/docs/guides/spa-vanilla/README.mdx +++ b/packages/console/src/assets/docs/guides/spa-vanilla/README.mdx @@ -40,16 +40,14 @@ pnpm add @logto/browser Import and init `LogtoClient` with configs: -
-  
+
     {`import LogtoClient from '@logto/browser';
 
 const logtoClient = new LogtoClient({
   endpoint: '${props.endpoint}',
   appId: '${props.app.id}',
 });`}
-  
-
+ @@ -72,15 +70,13 @@ First, let’s enter your redirect URI. E.g. `http://localhost:3000/callback`. Go back to your IDE/editor, use the following code to implement the sign-in button: -
-  
+
     {``}
-  
-
+ ### Handle redirect @@ -119,15 +115,13 @@ After signing out, it'll be great to redirect user back to your website. Let's a ### Implement a sign-out button -
-  
+
     {``}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/spa-vue/README.mdx b/packages/console/src/assets/docs/guides/spa-vue/README.mdx index b9a639977..154697da5 100644 --- a/packages/console/src/assets/docs/guides/spa-vue/README.mdx +++ b/packages/console/src/assets/docs/guides/spa-vue/README.mdx @@ -47,8 +47,7 @@ pnpm add @logto/vue Import and use `createLogto` to install Logto plugin: -
-  
+
     {`import { createLogto, LogtoConfig } from '@logto/vue';
 
 const config: LogtoConfig = {
@@ -60,8 +59,7 @@ const app = createApp(App);
 
 app.use(createLogto, config);
 app.mount("#app");`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/spa-webflow/README.mdx b/packages/console/src/assets/docs/guides/spa-webflow/README.mdx index 1ad4cf7cf..e36997b9f 100644 --- a/packages/console/src/assets/docs/guides/spa-webflow/README.mdx +++ b/packages/console/src/assets/docs/guides/spa-webflow/README.mdx @@ -22,8 +22,7 @@ In this step, we'll add global-level custom code to your Webflow site. Since NPM Open the "Site settings" page, and navigate to the "Custom code" section. Add the following code to the "Head code" section. -
-  
+
     {``}
-  
-
+ @@ -59,15 +57,13 @@ First, let’s enter your redirect URI. E.g. `https://your-awesome-site.webflow. Return to your Webflow designer, drag and drop a "Sign in" button to the home page, and assign it an ID “sign-in” for later reference using `getElementById()`. -
-  
+
     {``}
-  
-
+ ### Handle redirect @@ -99,13 +95,11 @@ After signing out, it'll be great to redirect user back to your website. Let's a Return to the Webflow designer, and add a “Sign out” button on your home page. Similarly, assign an ID “sign-out” to the button, and add the following code to the page-level custom code. -
-  
+
     {`const signOutButton = document.getElementById('sign-out');
 const onClickSignOut = () => logtoClient.signOut('${props.postLogoutRedirectUris[0] ?? 'https://your-awesome-site.webflow.io'}');
 signOutButton.addEventListener('click', onClickSignOut);`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-server/README.mdx b/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-server/README.mdx index 1258ea8a8..af12ef46d 100644 --- a/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-server/README.mdx +++ b/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-server/README.mdx @@ -24,8 +24,7 @@ dotnet add package Logto.AspNetCore.Authentication Open `Startup.cs` (or `Program.cs`) and add the following code to register Logto authentication middleware: -
-  
+
 {`using Logto.AspNetCore.Authentication;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -38,8 +37,7 @@ builder.Services.AddLogtoAuthentication(options =>
 });
 
 app.UseAuthentication();`}
-  
-
+ The `AddLogtoAuthentication` method will do the following things: diff --git a/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-wasm/README.mdx b/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-wasm/README.mdx index 757189964..1d111256d 100644 --- a/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-wasm/README.mdx +++ b/packages/console/src/assets/docs/guides/web-dotnet-core-blazor-wasm/README.mdx @@ -90,8 +90,7 @@ For example, set the URI to {props.sampleUrls.origin + 'SignedOutCallback' Add the following code to the `appsettings.json` file: -
-  
+
 {`// ...
   IdentityServer: {
     Authority: '${props.endpoint}oidc',
@@ -103,8 +102,7 @@ Add the following code to the `appsettings.json` file:
   },
 }
 `}
-    
-
+ diff --git a/packages/console/src/assets/docs/guides/web-dotnet-core-mvc/README.mdx b/packages/console/src/assets/docs/guides/web-dotnet-core-mvc/README.mdx index 8fa99eea2..4b109614e 100644 --- a/packages/console/src/assets/docs/guides/web-dotnet-core-mvc/README.mdx +++ b/packages/console/src/assets/docs/guides/web-dotnet-core-mvc/README.mdx @@ -24,8 +24,7 @@ dotnet add package Logto.AspNetCore.Authentication Open `Startup.cs` (or `Program.cs`) and add the following code to register Logto authentication middleware: -
-  
+
 {`using Logto.AspNetCore.Authentication;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -38,8 +37,7 @@ builder.Services.AddLogtoAuthentication(options =>
 });
 
 app.UseAuthentication();`}
-  
-
+ The `AddLogtoAuthentication` method will do the following things: diff --git a/packages/console/src/assets/docs/guides/web-dotnet-core/README.mdx b/packages/console/src/assets/docs/guides/web-dotnet-core/README.mdx index 245a9fe3a..0d9892434 100644 --- a/packages/console/src/assets/docs/guides/web-dotnet-core/README.mdx +++ b/packages/console/src/assets/docs/guides/web-dotnet-core/README.mdx @@ -24,8 +24,7 @@ dotnet add package Logto.AspNetCore.Authentication Open `Startup.cs` (or `Program.cs`) and add the following code to register Logto authentication middleware: -
-  
+
 {`using Logto.AspNetCore.Authentication;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -38,8 +37,7 @@ builder.Services.AddLogtoAuthentication(options =>
 });
 
 app.UseAuthentication();`}
-  
-
+ The `AddLogtoAuthentication` method will do the following things: diff --git a/packages/console/src/assets/docs/guides/web-express/README.mdx b/packages/console/src/assets/docs/guides/web-express/README.mdx index a498ee67a..bc957f100 100644 --- a/packages/console/src/assets/docs/guides/web-express/README.mdx +++ b/packages/console/src/assets/docs/guides/web-express/README.mdx @@ -48,8 +48,7 @@ pnpm add @logto/express cookie-parser express-session Import and initialize LogtoClient: -
-  
+
     {`import LogtoClient from '@logto/express';
 
 export const logtoClient = new LogtoClient({
@@ -58,8 +57,7 @@ export const logtoClient = new LogtoClient({
   appSecret: '${props.app.secret}',
   baseUrl: 'http://localhost:3000', // Change to your own base URL
 });`}
-  
-
+ @@ -70,15 +68,13 @@ export const logtoClient = new LogtoClient({ The SDK requires [express-session](https://www.npmjs.com/package/express-session) to be configured in prior. -
-  
+
     {`import cookieParser from 'cookie-parser';
 import session from 'express-session';
 
 app.use(cookieParser());
 app.use(session({ secret: '${generateStandardSecret()}', cookie: { maxAge: 14 * 24 * 60 * 60 } }));`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-go/README.mdx b/packages/console/src/assets/docs/guides/web-go/README.mdx index 3044cb21d..691056a82 100644 --- a/packages/console/src/assets/docs/guides/web-go/README.mdx +++ b/packages/console/src/assets/docs/guides/web-go/README.mdx @@ -144,8 +144,7 @@ sessionStorage := &SessionStorage{session: session} First, create a Logto config: -
-  
+
     {`// main.go
 func main() {
     // ...
@@ -158,8 +157,7 @@ func main() {
 
     // ...
 }`}
-  
-
+ Then, you can create a `LogtoClient` for each user request with the Logto config above: @@ -209,8 +207,7 @@ For example, if you add `http://localhost:8080/sign-in-callback` to your Redirec After the redirect URI is configured, we add a `sign-in` route to handle the sign-in request and also add an sign-in link on the home page: -
-  
+
     {`//main.go
 func main() {
     // ...
@@ -248,8 +245,7 @@ func main() {
 
     // ...
 }`}
-  
-
+ Now, when your user visit `http://localhost:8080/sign-in`, the user will be redirected to the Logto sign-in page. @@ -306,8 +302,7 @@ Assuming that you add `http://localhost:8080` to the Post Sign-out Redirect URI Now, let's add the `sign-out` route to handle the sign-out request and also add a sign-out link on the home page: -
-  
+
     {`//main.go
 func main() {
     // ...
@@ -346,8 +341,7 @@ func main() {
 
     // ...
 }`}
-  
-
+ After the user makes a signing-out request, Logto will clear all user authentication information in the session. diff --git a/packages/console/src/assets/docs/guides/web-java-spring-boot/README.mdx b/packages/console/src/assets/docs/guides/web-java-spring-boot/README.mdx index 7019654e2..b043d49b7 100644 --- a/packages/console/src/assets/docs/guides/web-java-spring-boot/README.mdx +++ b/packages/console/src/assets/docs/guides/web-java-spring-boot/README.mdx @@ -67,8 +67,7 @@ For maven, include the following dependencies in your `pom.xml` file: Register your application with Logto to get the client credentials and IdP configurations. Add the following configuration to your `application.properties` file: -
-  
+
     {`spring.security.oauth2.client.registration.logto.client-name=logto
 spring.security.oauth2.client.registration.logto.client-id=${props.app.id}
 spring.security.oauth2.client.registration.logto.client-secret=${props.app.secret}
@@ -81,8 +80,7 @@ spring.security.oauth2.client.provider.logto.issuer-uri=${props.endpoint}oidc
 spring.security.oauth2.client.provider.logto.authorization-uri=${props.endpoint}oidc/auth
 spring.security.oauth2.client.provider.logto.jwk-set-uri=${props.endpoint}oidc/jwks
   `}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-next-app-router/README.mdx b/packages/console/src/assets/docs/guides/web-next-app-router/README.mdx index 51cec13fd..26915db22 100644 --- a/packages/console/src/assets/docs/guides/web-next-app-router/README.mdx +++ b/packages/console/src/assets/docs/guides/web-next-app-router/README.mdx @@ -47,8 +47,7 @@ pnpm add @logto/next Prepare configuration for the Logto client. Create a new file `app/logto.ts` and add the following code: -
-  
+
     {`export const logtoConfig = {
   endpoint: '${props.endpoint}',
   appId: '${props.app.id}',
@@ -58,8 +57,7 @@ Prepare configuration for the Logto client. Create a new file `app/logto.ts` and
   cookieSecure: process.env.NODE_ENV === 'production',
 };
 `}
-  
-
+ - \ No newline at end of file + diff --git a/packages/console/src/assets/docs/guides/web-next-auth/README.mdx b/packages/console/src/assets/docs/guides/web-next-auth/README.mdx index baeeff260..badcf9665 100644 --- a/packages/console/src/assets/docs/guides/web-next-auth/README.mdx +++ b/packages/console/src/assets/docs/guides/web-next-auth/README.mdx @@ -31,8 +31,7 @@ Modify your API route config of Next Auth, if you are using Pages Router, the fi The following is an example of App Router: -
-  
+
     {`import NextAuth from 'next-auth';
 
 const handler = NextAuth({
@@ -64,8 +63,7 @@ const handler = NextAuth({
 });
 
 export { handler as GET, handler as POST };`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-next/README.mdx b/packages/console/src/assets/docs/guides/web-next/README.mdx index 0313e9ddd..fa6100178 100644 --- a/packages/console/src/assets/docs/guides/web-next/README.mdx +++ b/packages/console/src/assets/docs/guides/web-next/README.mdx @@ -47,8 +47,7 @@ pnpm add @logto/next Import and initialize LogtoClient: -
-  
+
     {`// libraries/logto.js
 import LogtoClient from '@logto/next';
 
@@ -60,8 +59,7 @@ export const logtoClient = new LogtoClient({
   cookieSecret: '${generateStandardSecret()}', // Auto-generated 32 digit secret
   cookieSecure: process.env.NODE_ENV === 'production',
 });`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-nuxt/README.mdx b/packages/console/src/assets/docs/guides/web-nuxt/README.mdx index 3ce9c63ca..d4bf7ef8e 100644 --- a/packages/console/src/assets/docs/guides/web-nuxt/README.mdx +++ b/packages/console/src/assets/docs/guides/web-nuxt/README.mdx @@ -46,7 +46,7 @@ pnpm add @logto/nuxt -In your Nuxt config file (`next.config.ts`), add the Logto module: +In your Nuxt config file (`nuxt.config.ts`), add the Logto module: ```ts export default defineNuxtConfig({ @@ -57,9 +57,8 @@ export default defineNuxtConfig({ The minimal configuration for the module is as follows: -
-  
-    {`export default defineNuxtConfig({
+
+{`export default defineNuxtConfig({
   modules: ['@logto/nuxt'],
   runtimeConfig: {
     logto: {
@@ -71,20 +70,17 @@ The minimal configuration for the module is as follows:
   },
   // ...other configurations
 });`}
-  
-
+ Since these information are sensitive, it's recommended to use environment variables (`.env`): -
-  
+
     {`NUXT_LOGTO_ENDPOINT=${props.endpoint}
 NUXT_LOGTO_APP_ID=${props.app.id}
 NUXT_LOGTO_APP_SECRET=${props.app.secret}
 NUXT_LOGTO_COOKIE_ENCRYPTION_KEY=${cookieEncryptionKey} # Random-generated
 `}
-  
-
+ See [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config) for more information. diff --git a/packages/console/src/assets/docs/guides/web-php/README.mdx b/packages/console/src/assets/docs/guides/web-php/README.mdx index 08ad78249..49122bc1a 100644 --- a/packages/console/src/assets/docs/guides/web-php/README.mdx +++ b/packages/console/src/assets/docs/guides/web-php/README.mdx @@ -26,8 +26,7 @@ composer require logto/sdk Insert the following code into your PHP file: -
-  
+
 {`use logto\sdk\LogtoClient;
 use Logto\Sdk\LogtoConfig;
 
@@ -38,8 +37,7 @@ $client = new LogtoClient(
     appSecret: "${props.app.secret}",
   ),
 );`}
-  
-
+ By default, the SDK uses the built-in PHP session to store the Logto data. If you want to use other storage, you can pass a custom storage object as the second parameter: @@ -62,23 +60,19 @@ First, let’s enter your redirect URI. E.g. {props.sampleUrls.callback} -
-  
+
 {`Route::get('/sign-in', function () {
   return redirect($client->signIn('${props.redirectUris[0] || props.sampleUrls.callback}'));
 });`}
-  
-
+ If you want to show the sign-up page on the first screen, you can set `interactionMode` to `signUp`: -
-  
+
 {`Route::get('/sign-in', function () {
   return redirect($client->signIn('${props.redirectUris[0] || props.sampleUrls.callback}', InteractionMode::signUp));
 });`}
-  
-
+ Now, whenever your users visit `/sign-in`, it will start a new sign-in attempt and redirect the user to the Logto sign-in page. @@ -112,16 +106,14 @@ To clean up the Python session and Logto session, we can designate a post sign-o And a sign-out route can be implemented as follows: -
-  
+
 {`Route::get('/sign-out', function () {
   return redirect(
     // Redirect the user to the home page after a successful sign-out
     $client->signOut('${props.postLogoutRedirectUris[0] || props.sampleUrls.origin}')
   );
 });`}
-  
-
+ The post sign-out redierct URI is optional, and if not provided, the user will be redirected to a Logto default page after a successful sign-out (without redirecting back to your application). diff --git a/packages/console/src/assets/docs/guides/web-python/README.mdx b/packages/console/src/assets/docs/guides/web-python/README.mdx index c29d61faf..5900e8198 100644 --- a/packages/console/src/assets/docs/guides/web-python/README.mdx +++ b/packages/console/src/assets/docs/guides/web-python/README.mdx @@ -24,8 +24,7 @@ pip install logto # or `poetry add logto` or whatever you use Insert the following code into your Python file: -
-  
+
 {`from logto import LogtoClient, LogtoConfig
 
 client = LogtoClient(
@@ -35,8 +34,7 @@ client = LogtoClient(
         appSecret="${props.app.secret}",
     )
 )`}
-  
-
+ Also replace the default memory storage with a persistent storage, for example: @@ -71,21 +69,18 @@ First, let’s enter your redirect URI. E.g. {props.sampleUrls.callback} -
-  
+
 {`@app.route("/sign-in")
 async def sign_in():
     # Get the sign-in URL and redirect the user to it
     return redirect(await client.signIn(
         redirectUri="${props.redirectUris[0] || props.sampleUrls.callback}",
     ))`}
-  
-
+ If you want to show the sign-up page on the first screen, you can set `interactionMode` to `signUp`: -
-  
+
 {`@app.route("/sign-in")
 async def sign_in():
     # Get the sign-in URL and redirect the user to it
@@ -93,8 +88,7 @@ async def sign_in():
         redirectUri="${props.redirectUris[0] || props.sampleUrls.callback}",
         interactionMode="signUp", # Show the sign-up page on the first screen
     ))`}
-  
-
+ Now, whenever your users visit `/sign-in`, it will start a new sign-in attempt and redirect the user to the Logto sign-in page. @@ -104,8 +98,7 @@ Now, whenever your users visit `/sign-in`, it will start a new sign-in attempt a After the user signs in, Logto will redirect the user to the callback URL you set in the Logto Console. In this example, we use `/callback` as the callback URL: -
-  
+
 {`@app.route("/callback")
 async def callback():
     try:
@@ -115,8 +108,7 @@ async def callback():
         # Change this to your error handling logic
         return "Error: " + str(e)
 `}
-  
-
+ @@ -128,8 +120,7 @@ To clean up the Python session and Logto session, we can designate a post sign-o And a sign-out route can be implemented as follows: -
-  
+
 {`@app.route("/sign-out")
 async def sign_out():
     return redirect(
@@ -137,8 +128,7 @@ async def sign_out():
         await client.signOut(postLogoutRedirectUri="${props.postLogoutRedirectUris[0] || props.sampleUrls.origin}")
     )
 `}
-  
-
+ `postLogoutRedirectUri` is optional, and if not provided, the user will be redirected to a Logto default page after a successful sign-out (without redirecting back to your application). diff --git a/packages/console/src/assets/docs/guides/web-remix/README.mdx b/packages/console/src/assets/docs/guides/web-remix/README.mdx index 2c196c559..a476caf54 100644 --- a/packages/console/src/assets/docs/guides/web-remix/README.mdx +++ b/packages/console/src/assets/docs/guides/web-remix/README.mdx @@ -45,8 +45,7 @@ pnpm add @logto/remix Before initializing the SDK, we have to create a `SessionStorage` instance which takes care of the session persistence. In our case, we want to use a cookie-based session: -
-  
+
     {`
 // services/authentication.ts
 import { createCookieSessionStorage } from "@remix-run/node";
@@ -58,8 +57,7 @@ const sessionStorage = createCookieSessionStorage({
     secrets: '${generateStandardSecret()}', // Auto-generated secret
   },
 });`}
-  
-
+ @@ -70,8 +68,7 @@ const sessionStorage = createCookieSessionStorage({ Use the `sessionStorage` created in the previous step to initialize LogtoClient: -
-  
+
     {`// app/services/authentication.ts
 
 import { makeLogtoRemix } from "@logto/remix";
@@ -85,8 +82,7 @@ export const logto = makeLogtoRemix(
   },
   { sessionStorage }
 );`}
-  
-
+ diff --git a/packages/console/src/assets/docs/guides/web-ruby/README.mdx b/packages/console/src/assets/docs/guides/web-ruby/README.mdx index c94ffd883..0f19d4387 100644 --- a/packages/console/src/assets/docs/guides/web-ruby/README.mdx +++ b/packages/console/src/assets/docs/guides/web-ruby/README.mdx @@ -32,8 +32,7 @@ The following demonstration is for Ruby on Rails. However, you can apply the sam In the file where you want to initialize the Logto client (e.g. a base controller or a middleware), add the following code: -
-  
+
     {`require "logto/client"
 
 @client = LogtoClient.new(
@@ -46,13 +45,11 @@ In the file where you want to initialize the Logto client (e.g. a base controlle
   storage: LogtoClient::SessionStorage.new(the_session_object)
 )
 end`}
-  
-
+ For instance, in a Rails controller, the code might look like this: -
-  
+
     {`# app/controllers/sample_controller.rb
 require "logto/client"
 
@@ -75,8 +72,7 @@ class SampleController < ApplicationController
     )
   end
 end`}
-  
-
+ @@ -104,26 +100,22 @@ After signing out, it'll be great to redirect user back to your website. For exa Since the redirect URI has been set to {props.redirectUris[0] || 'http://localhost:3000/callback'}, it needs to be handled it in our application. In a Rails controller, you can add the following code:

-
-  
+
     {`# app/controllers/sample_controller.rb
 class SampleController < ApplicationController
   def ${props.redirectUris[0]?.split('/').pop() || 'callback'}
     @client.handle_sign_in_callback(url: request.original_url)
   end
 end`}
-  
-
+ And configure the route in `config/routes.rb`: -
-  
+
     {`Rails.application.routes.draw do
   get "${new URL(props.redirectUris[0] || 'http://localhost:3000/callback').pathname}", to: "sample#${props.redirectUris[0]?.split('/').pop() || 'callback'}"
 end`}
-  
-
+ @@ -133,8 +125,7 @@ end`} There are various ways to invoke sign-in and sign-out in your application. For example, you can implement two routes in your Rails application: -
-  
+
     {`# app/controllers/sample_controller.rb
 class SampleController < ApplicationController
   def sign_in
@@ -147,8 +138,7 @@ class SampleController < ApplicationController
 
   # ...
 end`}
-  
-
+ ```ruby # config/routes.rb diff --git a/packages/console/src/assets/docs/guides/web-sveltekit/README.mdx b/packages/console/src/assets/docs/guides/web-sveltekit/README.mdx index 3dbe09dc7..97b8ddb26 100644 --- a/packages/console/src/assets/docs/guides/web-sveltekit/README.mdx +++ b/packages/console/src/assets/docs/guides/web-sveltekit/README.mdx @@ -46,8 +46,7 @@ Create a `hooks.server.ts` file in your project `src` root if you don't have one In your `hooks.server.ts` file, add the following code to inject the Logto hook into your server: -
-  
+
     {`import { handleLogto } from '@logto/sveltekit';
 
 export const handle = handleLogto(
@@ -60,13 +59,11 @@ export const handle = handleLogto(
     encryptionKey: '${cookieEncryptionKey}', // Random-generated
   }
 );`}
-  
-
+ Since these information are sensitive, it's recommended to use environment variables: -
-  
+
     {`import { handleLogto } from '@logto/sveltekit';
 import { env } from '$env/dynamic/private';
 
@@ -80,8 +77,7 @@ export const handle = handleLogto(
     encryptionKey: env.LOGTO_COOKIE_ENCRYPTION_KEY,
   }
 );`}
-  
-
+ If you have multiple hooks, you can use [the sequence() helper function](https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks) to chain them: @@ -126,8 +122,7 @@ After signing out, it'll be great to redirect user back to your website. For exa In the page where you want to implement sign-in and sign-out, define the following actions: -
-  
+
     {`// +page.server.ts
 import type { Actions } from './$types';
 
@@ -142,8 +137,7 @@ export const actions: Actions = {
   },
 };
 `}
-  
-
+ Then use these actions in your Svelte component: diff --git a/packages/console/src/components/Guide/index.tsx b/packages/console/src/components/Guide/index.tsx index cebd7d168..9eee31256 100644 --- a/packages/console/src/components/Guide/index.tsx +++ b/packages/console/src/components/Guide/index.tsx @@ -1,15 +1,12 @@ import { type ApplicationResponse } from '@logto/schemas'; -import { MDXProvider } from '@mdx-js/react'; import classNames from 'classnames'; import { type LazyExoticComponent, Suspense, createContext, useContext } from 'react'; import { guides } from '@/assets/docs/guides'; import { type GuideMetadata } from '@/assets/docs/guides/types'; import Button from '@/ds-components/Button'; -import CodeEditor from '@/ds-components/CodeEditor'; import OverlayScrollbar from '@/ds-components/OverlayScrollbar'; -import TextLink from '@/ds-components/TextLink'; -import DetailsSummary from '@/mdx-components/DetailsSummary'; +import MdxProvider from '@/mdx-components/MdxProvider'; import NotFound from '@/pages/NotFound'; import StepsSkeleton from './StepsSkeleton'; @@ -66,36 +63,11 @@ function Guide({ className, guideId, isEmpty, isLoading, onClose }: Props) { {isLoading && } {isEmpty && !guide && } - { - const [, language] = /language-(\w+)/.exec(String(className ?? '')) ?? []; - - return language ? ( - - ) : ( - {String(children).trimEnd()} - ); - }, - a: ({ children, ...props }) => ( - - {children} - - ), - details: DetailsSummary, - }} - > + }> {GuideComponent && } - + {!isApiResourceGuide && (