Skip to content

README-tutorial-generator.md

Latest commit

 

History

History
100 lines (70 loc) · 5.15 KB

README-tutorial-generator.md

File metadata and controls

100 lines (70 loc) · 5.15 KB

Generating the "Build X with Y" tutorial

The "Build X with Y" tutorial is a series of step-by-step guides that help developers build their application with a specific pair of Logto SDK and connector. For example: "How to build Google sign-in with Next.js".

The plugin comes along with some built-in templates in the "/tutorial" folder.

  • _template_passwordless.mdx: For tutorials integrating with a passwordless (email and SMS) sign-in method.
  • _template_social.mdx: For tutorials integrating with a social sign-in method.
  • _template_sso.mdx: For tutorials integrating with a single sign-on (SSO) method.

Here's how you can add a new X & Y combination to the tutorials:

Add a new SDK

  1. Create a new SDK guide folder in "/docs/quick-starts". For example: "/docs/quick-starts/framework/react".
  2. Make sure there's a _for-tutorial.mdx fragment in the folder. This MDX fragment will be used in the tutorial as the SDK integration part.
  3. In the _for-tutorial.mdx fragment, re-use as much content as possible from the existing quick-starts guide of your SDK.
  4. Make sure the level of headings (h2 / h3) are correctly used.
  5. Make sure the "quick-start" guide frontmatter contains the additional necessary properties for the tutorial generator to work. For example:
---
language: c#
official_link: https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models#blazor-webassembly
app_type: Single page app
framework: .NET Core (Blazor WebAssembly)
tutorial_name: .NET Core (Blazor WebAssembly)
---

These are all necessary variables that are injected into the tutorial template by the generator plugin.

Property Description
language The programming language used in the SDK framework.
official_link The official documentation link of the SDK.
app_type The application type of application the SDK.
framework The name of the SDK used in Logto console.
tutorial_name (OPTIONAL) The customized alias of the SDK. If not provided, the sidebar_label will be used.

Re-generate the tutorials using pnpm build after you have made changes to the SDK guide.

Add a new connector

  1. Create a new connector guide folder in "/docs/integrations". For example: "/docs/integrations/social/google".
  2. Similar to SDK, each connector guide used in the tutorial should have a _integration.mdx fragment.
  3. Make sure the level of headings are properly handled in the fragment.
  4. Make sure the "integration" guide frontmatter contains the additional necessary properties for the tutorial generator to work. For example:
---
tutorial_name: AWS SES
tutorial_config_name: AWS SES email connector
tutorial_sign_up_identifier: Email address
---

These are all necessary variables that are injected into the tutorial template by the generator plugin.

Property Description
tutorial_name The name of the connector used in the tutorial.
tutorial_config_name The name of configuration used in the 3rd party service platform.
tutorial_sign_up_identifier (OPTIONAL) The sign-up identifier used in email or SMS template. Available options: Email address or Phone number

Re-generate the tutorials using pnpm build after you have made changes to the connector guide.

Add i18n translations

Whenever you make changes to the SDK or connector guides, or the tutorial templates, make sure to translate them to all supported locales.

Translate templates

Translate the templates if you made any changes to them. With the CLI command below, you can translate the templates to a specific locale.

node translate-tutorial-templates.mjs --locale fr

Translate original SDK and connector guides

Translate the guide fragments in both SDK (quick-starts) and connector (integrations) folders. Same as translating other documentation pages.

node translate.mjs --locale fr --sync --all

Check out the source code of translate.mjs to see how it works.

Re-generate the tutorials

Re-generate the tutorials using pnpm build.

Commit all the changes

Commit all changes to the Git repository. Including:

  • All _template-*.mdx files for all locales
  • All the generated tutorials (generated-*.mdx) for all locales
  • The metadata.json file (intermittent file generated by the tutorial generator)