refactor: connector fragments used in generating tutorials

logto-io · Jan 2, 2025 · 5081c1a · 5081c1a
1 parent 0bdd416
commit 5081c1a
Show file tree

Hide file tree

Showing 299 changed files with 2,344 additions and 4,836 deletions.
diff --git a/docs/connectors/social.mdx b/docs/connectors/social.mdx
@@ -139,7 +139,7 @@ Please note the following settings:
 
 Once you create a social connector successfully, you can enable it as a Social login button (e.g., Continue with Google) in Sign-in Experience.
 
-1. Navigate to <CloudLink to="/sign-in-experience/sign-up-and-sign-in">Console > Sign-in experience >Sign-up and sign-in</CloudLink>.
+1. Navigate to <CloudLink to="/sign-in-experience/sign-up-and-sign-in">Console > Sign-in experience > Sign-up and sign-in</CloudLink>.
 2. (Optional) Choose "Not applicable" for sign-up identifier if you need social login only.
 3. Add configured social connectors to the "Social sign-in" section.
 4. Reorder connectors as needed.

diff --git a/docs/integrations/email/aws-ses/README.mdx b/docs/integrations/email/aws-ses/README.mdx
@@ -9,6 +9,8 @@ sidebar_custom_props:
 
 import GuideTip from '../../fragments/_guide-tip.mdx';
 
+import Integration from './_integration.mdx';
+
 # Set up email verification with AWS Direct Mail
 
 The official Logto connector for AWS connector for direct mail service.
@@ -21,55 +23,4 @@ Amazon SES is a cloud email service provider that can integrate into any applica
 
 Logto team to call the Amazon Simple Email Service APIs, with the help of which Logto end-users can register and sign in to their Logto account via mail verification code.
 
-## Configure a mail service in the AWS service console \{#configure-a-mail-service-in-the-aws-service-console}
-
-### Register AWS account \{#register-aws-account}
-
-Go to [AWS](https://aws.amazon.com/) and register an account.
-
-### Create a identity \{#create-a-identity}
-
-- Go to `Amazon Simple Email Service` Console
-- Create an identity, choose one of the following options
-  - Create an domain
-  - Create an email address
-
-### Configuration of the connector \{#configuration-of-the-connector}
-
-1. Click your username in the upper right corner of the Amazon console to enter `Security Credentials`. If you don't have one, create an `AccessKey` and save it carefully.
-2. Complete the settings of the `Amazon Simple Email Service` connector:
-   - Use the `AccessKey ID` and `AccessKey Secret` obtained in step 1 to fill in `accessKeyId` and `accessKeySecret` respectively.
-   - `region`: Fill in the `region` field with the region of the identity you use to send mail.
-   - `emailAddress`: The email address you use to send mail, in the format of `Logto\<[email protected]>` or `\<[email protected]>`
-
-the following parameters are optional; parameters description can be found in the [AWS SES API documentation](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html).
-
-- `feedbackForwardingEmailAddress`
-- `feedbackForwardingEmailAddressIdentityArn`
-- `configurationSetName`
-
-### Test the Amazon SES connector \{#test-the-amazon-ses-connector}
-
-You can type in an email address and click on "Send" to see whether the settings work before "Save and Done".
-
-That's it. Don't forget to [Enable connector in sign-in experience](/connectors/email-connectors/#enable-email-sign-up-or-sign-in).
-
-### Configure types \{#configure-types}
-
-| Name                                      | Type              |
-| ----------------------------------------- | ----------------- |
-| accessKeyId                               | string            |
-| accessKeySecret                           | string            |
-| region                                    | string            |
-| emailAddress                              | string (OPTIONAL) |
-| emailAddressIdentityArn                   | string (OPTIONAL) |
-| feedbackForwardingEmailAddress            | string (OPTIONAL) |
-| feedbackForwardingEmailAddressIdentityArn | string (OPTIONAL) |
-| configurationSetName                      | string (OPTIONAL) |
-| templates                                 | Template[]        |
-
-| Template Properties | Type        | Enum values                                             |
-| ------------------- | ----------- | ------------------------------------------------------- |
-| subject             | string      | N/A                                                     |
-| content             | string      | N/A                                                     |
-| usageType           | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |
+<Integration />
diff --git a/...l/build-with-logto/_connector-aws-ses.mdx → ...tegrations/email/aws-ses/_integration.mdx b/...l/build-with-logto/_connector-aws-ses.mdx → ...tegrations/email/aws-ses/_integration.mdx
@@ -1,45 +1,37 @@
-### Configure a mail service in the AWS service console
+## Configure a mail service in the AWS service console \{#configure-a-mail-service-in-the-aws-service-console}
 
-Amazon SES is a cloud email service provider that can integrate into any application for bulk email sending.
-
-Logto core calls the Amazon Simple Email Service APIs via this connector, with the help of which Logto end-users can register and sign in to their Logto account via email verification code.
-
-> 💡 **Tip**
->
-> You can skip some sections if you have already finished.
-
-#### Register AWS account
+### Register AWS account \{#register-aws-account}
 
 Go to [AWS](https://aws.amazon.com/) and register an account.
 
-#### Create a identity
+### Create a identity \{#create-a-identity}
 
 - Go to `Amazon Simple Email Service` Console
 - Create an identity, choose one of the following options
-  - Create a domain
+  - Create an domain
   - Create an email address
 
-#### Configuration of the connector
+### Configuration of the connector \{#configuration-of-the-connector}
 
 1. Click your username in the upper right corner of the Amazon console to enter `Security Credentials`. If you don't have one, create an `AccessKey` and save it carefully.
 2. Complete the settings of the `Amazon Simple Email Service` connector:
    - Use the `AccessKey ID` and `AccessKey Secret` obtained in step 1 to fill in `accessKeyId` and `accessKeySecret` respectively.
    - `region`: Fill in the `region` field with the region of the identity you use to send mail.
-   - `emailAddress`: The email address you use to send mail, in the format of `Logto<[email protected]>` or `<[email protected]>`
+   - `emailAddress`: The email address you use to send mail, in the format of `Logto\<[email protected]>` or `\<[email protected]>`
 
 the following parameters are optional; parameters description can be found in the [AWS SES API documentation](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html).
 
 - `feedbackForwardingEmailAddress`
 - `feedbackForwardingEmailAddressIdentityArn`
 - `configurationSetName`
 
-#### Test the Amazon SES connector
+### Test the Amazon SES connector \{#test-the-amazon-ses-connector}
 
 You can type in an email address and click on "Send" to see whether the settings work before "Save and Done".
 
-That's it. Don't forget to enable connector in sign-in experience.
+That's it. Don't forget to [Enable connector in sign-in experience](/connectors/email-connectors/#enable-email-sign-up-or-sign-in).
 
-#### Configure types
+### Configure types \{#configure-types}
 
 | Name                                      | Type              |
 | ----------------------------------------- | ----------------- |

diff --git a/docs/integrations/email/sendgrid/README.mdx b/docs/integrations/email/sendgrid/README.mdx
@@ -0,0 +1,23 @@
+---
+slug: /integrations/sendgrid-email
+sidebar_label: SendGrid Email
+sidebar_custom_props:
+  description: SendGrid is a communication platform for transactional and marketing email.
+  logoFilename: 'sendgrid.svg'
+---
+
+import GuideTip from '../../fragments/_guide-tip.mdx';
+
+import Integration from './_integration.mdx';
+
+# Set up email verification with SendGrid Email
+
+The official Logto connector for SendGrid email service.
+
+<GuideTip />
+
+## Get started \{#get-started}
+
+SendGrid (i.e. Twilio SendGrid) is a customer communication platform for transactional and marketing email. We can use its email sending function to send a _verification code_.
+
+<Integration />
diff --git a/...egrations/email/sendgrid-email/README.mdx → ...egrations/email/sendgrid/_integration.mdx b/...egrations/email/sendgrid-email/README.mdx → ...egrations/email/sendgrid/_integration.mdx
@@ -1,23 +1,3 @@
----
-slug: /integrations/sendgrid-email
-sidebar_label: SendGrid Email
-sidebar_custom_props:
-  description: SendGrid is a communication platform for transactional and marketing email.
-  logoFilename: 'sendgrid.svg'
----
-
-import GuideTip from '../../fragments/_guide-tip.mdx';
-
-# Set up email verification with SendGrid Email
-
-The official Logto connector for SendGrid email service.
-
-<GuideTip />
-
-## Get started \{#get-started}
-
-SendGrid (i.e. Twilio SendGrid) is a customer communication platform for transactional and marketing email. We can use its email sending function to send a _verification code_.
-
 ## Register SendGrid account \{#register-sendgrid-account}
 
 Create a new account at [SendGrid website](https://app.sendgrid.com/). You may skip this step if you've already got an account.

diff --git a/docs/integrations/sms/twilio/README.mdx b/docs/integrations/sms/twilio/README.mdx
@@ -0,0 +1,27 @@
+---
+slug: /integrations/twilio-sms
+sidebar_label: Twilio SMS
+sidebar_custom_props:
+  description: Twilio provides programmable communication tools for phone calls and messages.
+  logoFilename: 'twilio.svg'
+---
+
+import GuideTip from '../../fragments/_guide-tip.mdx';
+
+import Integration from './_integration.mdx';
+
+# Set up SMS verification with Twilio SMS
+
+The official Logto connector for Twilio short message service.
+
+<GuideTip />
+
+## Get started \{#get-started}
+
+Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and other communication functions. We can send the "verification code" text messages through its web service APIs.
+
+<Integration />
+
+## Reference \{#reference}
+
+<Url href="https://www.twilio.com/docs/api/errors">Twilio - Error and Warning Dictionary</Url>
diff --git a/docs/integrations/sms/twilio-sms/README.mdx → .../integrations/sms/twilio/_integration.mdx b/docs/integrations/sms/twilio-sms/README.mdx → .../integrations/sms/twilio/_integration.mdx
@@ -1,23 +1,3 @@
----
-slug: /integrations/twilio-sms
-sidebar_label: Twilio SMS
-sidebar_custom_props:
-  description: Twilio provides programmable communication tools for phone calls and messages.
-  logoFilename: 'twilio.svg'
----
-
-import GuideTip from '../../fragments/_guide-tip.mdx';
-
-# Set up SMS verification with Twilio SMS
-
-The official Logto connector for Twilio short message service.
-
-<GuideTip />
-
-## Get started \{#get-started}
-
-Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and other communication functions. We can send the "verification code" text messages through its web service APIs.
-
 ## Register Twilio account \{#register-twilio-account}
 
 Create a new account on [Twilio](https://www.twilio.com). (Jump to the next step if you already have one.)
@@ -77,7 +57,3 @@ That's it. Don't forget to [Enable connector in sign-in experience](/connectors/
 | ------------------- | ----------- | ------------------------------------------------------- |
 | content             | string      | N/A                                                     |
 | usageType           | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |
-
-## Reference \{#reference}
-
-<Url href="https://www.twilio.com/docs/api/errors">Twilio - Error and Warning Dictionary</Url>
diff --git a/docs/integrations/social/apple/README.mdx b/docs/integrations/social/apple/README.mdx
@@ -8,6 +8,8 @@ sidebar_custom_props:
 
 import GuideTip from '../../fragments/_guide-tip.mdx';
 
+import Integration from './_integration.mdx';
+
 # Set up social login with Apple
 
 The official Logto connector for Apple social sign-in.
@@ -18,67 +20,7 @@ The official Logto connector for Apple social sign-in.
 
 If you don't know the concept of the connector or don't know how to add this connector to your Sign-in experience, please see [Logto tutorial](/connectors/social-connectors).
 
-:::note
-
-Apple sign-in is required for AppStore if you have other social sign-in methods in your app.
-Having Apple sign-in on Android devices is great if you also provide an Android app.
-
-:::
-
-You need to enroll [Apple Developer Program](https://developer.apple.com/programs/) before continuing.
-
-### Enable Sign in with Apple for your app \{#enable-sign-in-with-apple-for-your-app}
-
-:::caution
-
-Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID).
-
-:::
-
-You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/bundleId).
-
-![Enable Sign in with Apple](./assets/enable-sign-in-with-apple-in-xcode.png)
-
-See the "Enable an App ID" section in [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple) for more info.
-
-### Create an identifier \{#create-an-identifier}
-
-1. Visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/serviceId), then click the "+" button next to "Identifier".
-2. In the "Register a new identifier" page, choose "Services IDs" and click "Continue".
-3. Fill out "Description" and "Identifier" (E.g., `Logto Test` and `io.logto.test`), then click "Continue".
-4. Double-check the info and click "Register".
-
-### Enable Sign in with Apple for your identifier \{#enable-sign-in-with-apple-for-your-identifier}
-
-Click the identifier you just created. Check "Sign in with Apple" on the details page and click "Configure".
-
-![Enable Sign in with Apple](./assets/enable-sign-in-with-apple.png)
-
-In the opening modal, select the App ID you just enabled Sign in with Apple.
-
-Enter the domain of your Logto instance without protocol and port, e.g., `your.logto.domain`; then enter the "Return URL" (i.e., Redirect URI), which is the Logto URL with `/callback/${connector_id}`, e.g., `https://your.logto.domain/callback/apple-universal`. You can get the randomly generated `connector_id` after creating Apple connector in Admin Console.
-
-![domain-and-url](./assets/domain-and-url.png)
-
-Click "Next" then "Done" to close the modal. Click "Continue" on the top-right corner, then click "Save" to save your configuration.
-
-:::caution
-
-Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain.
-
-If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS.
-
-:::
-
-## Configure scope \{#configure-scope}
-
-To get user's email from Apple, you need to configure the scope to include `email`. For both email and name, you can use `name email` as the scope. See [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113) for more info.
-
-:::note
-
-The user may choose to hide their email address from your app. In this case, you will not be able to retrieve the real email address. An email address like `[email protected]` will be returned instead.
-
-:::
+<Integration />
 
 ### Pitfalls of configuring scope \{#pitfalls-of-configuring-scope}
 

diff --git a/...ial/build-with-logto/_connector-apple.mdx → ...ntegrations/social/apple/_integration.mdx b/...ial/build-with-logto/_connector-apple.mdx → ...ntegrations/social/apple/_integration.mdx
@@ -1,30 +1,34 @@
-> ℹ️ **Note**
->
-> Apple sign-in is required for AppStore if you have other social sign-in methods in your app.
-> Having Apple sign-in on Android devices is great if you also provide an Android app.
+:::note
+
+Apple sign-in is required for AppStore if you have other social sign-in methods in your app.
+Having Apple sign-in on Android devices is great if you also provide an Android app.
+
+:::
 
 You need to enroll [Apple Developer Program](https://developer.apple.com/programs/) before continuing.
 
-### Enable Sign in with Apple for your app
+### Enable Sign in with Apple for your app \{#enable-sign-in-with-apple-for-your-app}
+
+:::caution
+
+Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID).
 
-> ⚠️ **Caution**
->
-> Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID).
+:::
 
 You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/bundleId).
 
 ![Enable Sign in with Apple](./assets/enable-sign-in-with-apple-in-xcode.png)
 
 See the "Enable an App ID" section in [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple) for more info.
 
-### Create an identifier
+### Create an identifier \{#create-an-identifier}
 
 1. Visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/serviceId), then click the "+" button next to "Identifier".
 2. In the "Register a new identifier" page, choose "Services IDs" and click "Continue".
 3. Fill out "Description" and "Identifier" (E.g., `Logto Test` and `io.logto.test`), then click "Continue".
 4. Double-check the info and click "Register".
 
-### Enable Sign in with Apple for your identifier
+### Enable Sign in with Apple for your identifier \{#enable-sign-in-with-apple-for-your-identifier}
 
 Click the identifier you just created. Check "Sign in with Apple" on the details page and click "Configure".
 
@@ -38,24 +42,20 @@ Enter the domain of your Logto instance without protocol and port, e.g., `your.l
 
 Click "Next" then "Done" to close the modal. Click "Continue" on the top-right corner, then click "Save" to save your configuration.
 
-> ⚠️ **Caution**
->
-> Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain.
->
-> If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS.
+:::caution
+
+Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain.
+
+If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS.
+
+:::
+
+## Configure scope \{#configure-scope}
 
-### Compose the connector JSON
+To get user's email from Apple, you need to configure the scope to include `email`. For both email and name, you can use `name email` as the scope. See [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113) for more info.
 
-You need to use the identifier that fills in the [Create an identifier](#create-an-identifier) section to compose the JSON:
+:::note
 
-```json
-{
-  "clientId": "io.logto.test"
-}
-```
+The user may choose to hide their email address from your app. In this case, you will not be able to retrieve the real email address. An email address like `[email protected]` will be returned instead.
 
-> ℹ️ **Note**
->
-> This connector doesn't support customizing `scope` (e.g., name, email) yet since Apple requires `form_post` response mode when `scope` is not empty, which is incompatible with the current connector design.
->
-> We'll figure out this later.
+:::