refactor(console): update ruby guide (#6116)

* refactor(console): update ruby guide

* refactor(console): support further readings

* refactor(console): reorg docs

packages/console/src/assets/docs/fragments/_redirect_uris.mdx

@@ -1,3 +1,6 @@
+import InlineNotification from '@/ds-components/InlineNotification';
+import UriInputField from '@/mdx-components/UriInputField';
+
 Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:
 
 ```mermaid
@@ -18,3 +21,15 @@ Regarding redirect-based sign-in:
 To learn more about the rationale and benefits of redirect-based sign-in, see [Logto sign-in experience explained](https://docs.logto.io/docs/tutorials/get-started/sign-in-experience).
 
 ---
+
+<InlineNotification>
+  In the following steps, we assume your app is running on <code>http://localhost:3000</code>.
+</InlineNotification>
+
+Now, let's enter your redirect URI. E.g. `http://localhost:3000/callback`.
+
+<UriInputField name="redirectUris" />
+
+Just like signing in, users should be redirected to Logto for signing out of the shared session. Once finished, it would be great to redirect the user back to your website. For example, add `http://localhost:3000` as the post sign-out redirect URI below.
+
+<UriInputField name="postLogoutRedirectUris" />

packages/console/src/assets/docs/guides/m2m-general/index.ts

@@ -7,10 +7,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
   description: 'Enables direct communication between machines.',
   target: ApplicationType.MachineToMachine,
   isFeatured: true,
-  fullGuide: {
-    title: 'Full machine-to-machine integration tutorial',
-    url: 'https://docs.logto.io/quick-starts/m2m',
-  },
+  fullGuide: 'm2m',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/native-android/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'kotlin',
     path: 'android-sample-kotlin',
   },
-  fullGuide: {
-    title: 'Full Android SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/android',
-  },
+  fullGuide: 'android',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/native-expo/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'react-native',
     path: 'packages/rn-sample',
   },
-  fullGuide: {
-    title: 'Full Expo (React Native) guide',
-    url: 'https://docs.logto.io/quick-starts/expo',
-  },
+  fullGuide: 'expo',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/spa-angular/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/angular-sample',
   },
-  fullGuide: {
-    title: 'Full Angular guide',
-    url: 'https://docs.logto.io/quick-starts/angular',
-  },
+  fullGuide: 'angular',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/spa-react/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     path: 'packages/react-sample',
   },
   isFeatured: true,
-  fullGuide: {
-    title: 'Full React SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/react',
-  },
+  fullGuide: 'react',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/spa-vanilla/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/browser-sample',
   },
-  fullGuide: {
-    title: 'Full vanilla JS SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/vanilla-js',
-  },
+  fullGuide: 'vanilla-js',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/spa-vue/index.ts

@@ -12,10 +12,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     path: 'packages/vue-sample',
   },
   isFeatured: true,
-  fullGuide: {
-    title: 'Full Vue SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/vue',
-  },
+  fullGuide: 'vue',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/types.ts

@@ -31,11 +31,14 @@ export type GuideMetadata = {
   /** Indicate whether the application is for third-party use */
   isThirdParty?: boolean;
 
-  /** The related complete guide for this guide which will be displayed in the 'Further readings' section. */
-  fullGuide?: {
+  /** The related complete guide url relative to the quick starts page (https://docs.logto.io/quick-starts). */
+  fullGuide?: string;
+
+  /** The related URLs to add to the further readings section. */
+  furtherReadings?: Array<{
     title: string;
-    url: string;
-  };
+    url: URL;
+  }>;
 };
 
 /** The guide instance to build in the console. */

packages/console/src/assets/docs/guides/web-dotnet-core-blazor-server/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'csharp',
     path: '/',
   },
-  fullGuide: {
-    title: 'Full .NET Core (Blazor Server) integration tutorial',
-    url: 'https://docs.logto.io/quick-starts/dotnet-core/blazor-server',
-  },
+  fullGuide: 'dotnet-core/blazor-server',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-dotnet-core-blazor-wasm/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'csharp',
     path: '/',
   },
-  fullGuide: {
-    title: 'Full .NET Core (Blazor WASM) integration tutorial',
-    url: 'https://docs.logto.io/quick-starts/dotnet-core/blazor-wasm',
-  },
+  fullGuide: 'dotnet-core/blazor-wasm',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-dotnet-core-mvc/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'csharp',
     path: '/',
   },
-  fullGuide: {
-    title: 'Full .NET Core (MVC) integration tutorial',
-    url: 'https://docs.logto.io/quick-starts/dotnet-core/mvc',
-  },
+  fullGuide: 'dotnet-core/mvc',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-express/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/express-sample',
   },
-  fullGuide: {
-    title: 'Full Express SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/express',
-  },
+  fullGuide: 'express',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-go/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'go',
     path: 'gin-sample',
   },
-  fullGuide: {
-    title: 'Full Go SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/go',
-  },
+  fullGuide: 'go',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-next-app-router/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     path: 'packages/next-server-actions-sample',
   },
   isFeatured: true,
-  fullGuide: {
-    title: 'Full Next.js SDK tutorial',
-    url: 'https://docs.logto.io/sdk/next-app-router/',
-  },
+  fullGuide: 'next-app-router',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-next/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/next-sample',
   },
-  fullGuide: {
-    title: 'Full Next.js SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/next',
-  },
+  fullGuide: 'next',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-nuxt/README.mdx

@@ -5,7 +5,7 @@ import InlineNotification from '@/ds-components/InlineNotification';
 import Steps from '@/mdx-components/Steps';
 import Step from '@/mdx-components/Step';
 import Checkpoint from '../../fragments/_checkpoint.md';
-import SignInExplanation from '../../fragments/_sign_in_explanation.md';
+import RedirectUris from '../../fragments/_redirect_uris.mdx';
 import { generateStandardSecret } from '@logto/shared/universal';
 
 export const cookieEncryptionKey = generateStandardSecret();
@@ -79,21 +79,12 @@ See [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config) f
 
 </Step>
 
-<Step title="Configure your app">
+<Step 
+  title="Configure redirect URIs"
+  subtitle="2 URIs"
+>
 
-<SignInExplanation />
-
-<InlineNotification>
-  In the following steps, we assume your app is running on <code>http://localhost:3000</code>.
-</InlineNotification>
-
-Now, let's enter your redirect URI. E.g. `http://localhost:3000/callback`.
-
-<UriInputField name="redirectUris" />
-
-Just like signing in, users should be redirected to Logto for signing out of the shared session. Once finished, it would be great to redirect the user back to your website. For example, add `http://localhost:3000` as the post sign-out redirect URI below.
-
-<UriInputField name="postLogoutRedirectUris" />
+<RedirectUris />
 
 When registering `@logto/nuxt` module, it will do the following:
 

packages/console/src/assets/docs/guides/web-nuxt/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/nuxt',
   },
-  fullGuide: {
-    title: 'Full Nuxt guide',
-    url: 'https://docs.logto.io/quick-starts/nuxt',
-  },
+  fullGuide: 'nuxt',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-php/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'php',
     path: 'samples',
   },
-  fullGuide: {
-    title: 'Full PHP SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/php',
-  },
+  fullGuide: 'php',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-python/index.ts

@@ -10,10 +10,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'python',
     path: 'samples',
   },
-  fullGuide: {
-    title: 'Full Python SDK tutorial',
-    url: 'https://docs.logto.io/quick-starts/python',
-  },
+  fullGuide: 'python',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-ruby/README.mdx

@@ -1,6 +1,8 @@
 import UriInputField from '@/mdx-components/UriInputField';
 import InlineNotification from '@/ds-components/InlineNotification';
 import { generateStandardSecret } from '@logto/shared/universal';
+import RedirectUris from '../../fragments/_redirect_uris.mdx';
+import Checkpoint from '../../fragments/_checkpoint.md';
 import Steps from '@/mdx-components/Steps';
 import Step from '@/mdx-components/Step';
 
@@ -49,9 +51,8 @@ end`}
 
 For instance, in a Rails controller, the code might look like this:
 
-<Code className="language-ruby">
-    {`# app/controllers/sample_controller.rb
-require "logto/client"
+<Code title="app/controllers/sample_controller.rb" className="language-ruby">
+    {`require "logto/client"
 
 class SampleController < ApplicationController
   before_action :initialize_logto_client
@@ -81,13 +82,7 @@ end`}
   subtitle="2 URIs"
 >
 
-First, let's enter your redirect URI. E.g. `http://localhost:3000/callback`. [Redirect URI](https://www.oauth.com/oauth2-servers/redirect-uris/) is an OAuth 2.0 concept which implies the location should redirect after authentication.
-
-<UriInputField name="redirectUris" />
-
-After signing out, it'll be great to redirect user back to your website. For example, add `http://localhost:3000` as the post sign-out redirect URI below.
-
-<UriInputField name="postLogoutRedirectUris" />
+<RedirectUris />
 
 </Step>
 
@@ -100,18 +95,17 @@ After signing out, it'll be great to redirect user back to your website. For exa
   Since the redirect URI has been set to <code>{props.redirectUris[0] || 'http://localhost:3000/callback'}</code>, it needs to be handled it in our application. In a Rails controller, you can add the following code:
 </p>
 
-<Code className="language-ruby">
-    {`# app/controllers/sample_controller.rb
-class SampleController < ApplicationController
+<Code title="app/controllers/sample_controller.rb" className="language-ruby">
+    {`class SampleController < ApplicationController
   def ${props.redirectUris[0]?.split('/').pop() || 'callback'}
     @client.handle_sign_in_callback(url: request.original_url)
   end
 end`}
 </Code>
 
-And configure the route in `config/routes.rb`:
+And configure the route:
 
-<Code className="language-ruby">
+<Code title="config/routes.rb" className="language-ruby">
     {`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`}
@@ -125,9 +119,8 @@ 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:
 
-<Code className="language-ruby">
-    {`# app/controllers/sample_controller.rb
-class SampleController < ApplicationController
+<Code title="app/controllers/sample_controller.rb" className="language-ruby">
+    {`class SampleController < ApplicationController
   def sign_in
     @client.sign_in(redirect_uri: request.base_url + "${new URL(props.redirectUris[0] || 'http://localhost:3000/callback').pathname}")
   end
@@ -140,8 +133,7 @@ class SampleController < ApplicationController
 end`}
 </Code>
 
-```ruby
-# config/routes.rb
+```ruby title="config/routes.rb"
 Rails.application.routes.draw do
   get "/sign_in", to: "sample#sign_in"
   get "/sign_out", to: "sample#sign_out"
@@ -152,8 +144,7 @@ end
 
 Then you can create buttons or links in your views to trigger these actions. For example:
 
-```erb
-<!-- app/views/sample/index.html.erb -->
+```erb title="app/views/sample/index.html.erb"
 <% if @client.is_authenticated? %>
   <a href="<%= sign_out_path %>">Sign out</a>
 <% else %>
@@ -163,12 +154,17 @@ Then you can create buttons or links in your views to trigger these actions. For
 
 </Step>
 
+<Step title="Checkpoint: Test your app">
+
+<Checkpoint />
+
+</Step>
+
 <Step title="Display user information">
 
 To display the user's information, you can use the `@client.id_token_claims` method. For example, in a view:
 
-```erb
-<!-- app/views/sample/index.html.erb -->
+```erb title="app/views/sample/index.html.erb"
 <% if @client.is_authenticated? %>
   <p>Welcome, <%= @client.id_token_claims["name"] %></p>
 <% else %>

packages/console/src/assets/docs/guides/web-ruby/index.ts

@@ -8,6 +8,10 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     'Ruby is a dynamic, open-source programming language with a focus on simplicity and productivity.',
   target: ApplicationType.Traditional,
   isFeatured: true,
+  sample: {
+    repo: 'ruby',
+    path: 'logto-sample',
+  },
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-sveltekit/index.ts

@@ -11,10 +11,7 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
     repo: 'js',
     path: 'packages/sveltekit-sample',
   },
-  fullGuide: {
-    title: 'Full SvelteKit guide',
-    url: 'https://docs.logto.io/quick-starts/sveltekit',
-  },
+  fullGuide: 'sveltekit',
 });
 
 export default metadata;

packages/console/src/assets/docs/guides/web-wordpress/index.ts

@@ -6,10 +6,12 @@ const metadata: Readonly<GuideMetadata> = Object.freeze({
   name: 'WordPress',
   description: 'Integrate Logto into your WordPress app.',
   target: ApplicationType.Traditional,
-  fullGuide: {
-    title: 'Authorization and role mapping in WordPress',
-    url: 'https://blog.logto.io/integrate-with-wordpress-authorization/',
-  },
+  furtherReadings: [
+    {
+      title: 'Authorization and role mapping in WordPress',
+      url: new URL('https://blog.logto.io/integrate-with-wordpress-authorization/'),
+    },
+  ],
 });
 
 export default metadata;

packages/console/src/mdx-components/Steps/FurtherReadings.tsx

@@ -1,3 +1,4 @@
+import { appendPath } from '@silverhand/essentials';
 import { type Ref, forwardRef } from 'react';
 
 import { type GuideMetadata } from '@/assets/docs/guides/types';
@@ -7,20 +8,30 @@ import Step, { type Props as StepProps } from '../Step';
 
 type Props = Omit<StepProps, 'children'> & {
   readonly fullGuide: GuideMetadata['fullGuide'];
+  readonly furtherReadings: GuideMetadata['furtherReadings'];
 };
 
+const quickStartsUrl = new URL('https://docs.logto.io/quick-starts/');
+
 function FurtherReadings(props: Props, ref?: Ref<HTMLDivElement>) {
-  const { fullGuide, ...stepProps } = props;
+  const { fullGuide, furtherReadings, ...stepProps } = props;
   return (
     <Step ref={ref} {...stepProps}>
       <ul>
         {fullGuide && (
           <li>
-            <TextLink href={fullGuide.url} targetBlank="noopener">
-              {fullGuide.title}
+            <TextLink href={appendPath(quickStartsUrl, fullGuide).href} targetBlank="noopener">
+              Complete guide
             </TextLink>
           </li>
         )}
+        {furtherReadings?.map(({ title, url }) => (
+          <li key={title}>
+            <TextLink href={url.href} targetBlank="noopener">
+              {title}
+            </TextLink>
+          </li>
+        ))}
         <li>
           <TextLink href="https://docs.logto.io/docs/recipes/customize-sie/" targetBlank="noopener">
             Customize sign-in experience

packages/console/src/mdx-components/Steps/index.tsx

@@ -43,8 +43,14 @@ export default function Steps({ children: reactChildren }: Props) {
   const isApiResourceGuide = metadata.target === 'API';
 
   const furtherReadings = useMemo(
-    () => <FurtherReadings title="Further readings" fullGuide={metadata.fullGuide} />,
-    [metadata.fullGuide]
+    () => (
+      <FurtherReadings
+        title="Further readings"
+        fullGuide={metadata.fullGuide}
+        furtherReadings={metadata.furtherReadings}
+      />
+    ),
+    [metadata.fullGuide, metadata.furtherReadings]
   );
   const children: Array<ReactElement<StepProps, typeof Step>> = useMemo(() => {
     const steps = (Array.isArray(reactChildren) ? reactChildren : [reactChildren]).filter(