From 1c344d0d7f02c6d6b36d0cc73114b75522d355c8 Mon Sep 17 00:00:00 2001 From: giancarlo Date: Thu, 11 Apr 2024 11:27:16 +0800 Subject: [PATCH] Update layout, navigation, and content for documentation pages Enhanced the documentation pages by updating the layout with aesthetic adjustments and adding better navigation elements. New documentation content was added: 'Authentication', 'Getting Started', and their child pages. This ensures users have a clearer path when viewing, navigating, and accessing the information they need. "Read more" fallback label was added to the documentation cards for better accessibility. --- .../blog/_components/html-renderer.module.css | 2 +- .../app/(marketing)/docs/[...slug]/page.tsx | 5 +- .../docs/_components/docs-card.tsx | 6 +- .../docs/_components/docs-cards.tsx | 7 ++- .../docs/_components/docs-navigation.tsx | 32 +++++------ apps/web/app/(marketing)/docs/page.tsx | 8 ++- .../authentication/authentication.mdoc | 24 ++++++++ .../authentication/configuration.mdoc | 55 +++++++++++++++++++ .../getting-started/getting-started.mdoc | 27 +++++++++ .../installing-dependencies.mdoc | 21 +++++++ apps/web/public/locales/en/marketing.json | 1 + packages/cms/keystatic/src/client.ts | 8 ++- 12 files changed, 167 insertions(+), 29 deletions(-) create mode 100644 apps/web/content/documentation/authentication/authentication.mdoc create mode 100644 apps/web/content/documentation/authentication/configuration.mdoc create mode 100644 apps/web/content/documentation/getting-started/getting-started.mdoc create mode 100644 apps/web/content/documentation/getting-started/installing-dependencies.mdoc diff --git a/apps/web/app/(marketing)/blog/_components/html-renderer.module.css b/apps/web/app/(marketing)/blog/_components/html-renderer.module.css index 00be94fb9..f445c163d 100644 --- a/apps/web/app/(marketing)/blog/_components/html-renderer.module.css +++ b/apps/web/app/(marketing)/blog/_components/html-renderer.module.css @@ -93,5 +93,5 @@ For more info: https://github.com/tailwindlabs/tailwindcss/issues/3258#issuecomm } .HTML pre { - @apply my-6 text-sm text-current; + @apply my-6 text-sm text-current bg-muted p-6; } diff --git a/apps/web/app/(marketing)/docs/[...slug]/page.tsx b/apps/web/app/(marketing)/docs/[...slug]/page.tsx index 53a463612..7b183c74e 100644 --- a/apps/web/app/(marketing)/docs/[...slug]/page.tsx +++ b/apps/web/app/(marketing)/docs/[...slug]/page.tsx @@ -4,6 +4,7 @@ import { notFound } from 'next/navigation'; import { ContentRenderer, createCmsClient } from '@kit/cms'; import { If } from '@kit/ui/if'; +import { Separator } from '@kit/ui/separator'; import { withI18n } from '~/lib/i18n/with-i18n'; @@ -56,7 +57,9 @@ async function DocumentationPage({ params }: PageParams) { - + 0}> + + diff --git a/apps/web/app/(marketing)/docs/_components/docs-card.tsx b/apps/web/app/(marketing)/docs/_components/docs-card.tsx index f08c4d988..a95f78ec1 100644 --- a/apps/web/app/(marketing)/docs/_components/docs-card.tsx +++ b/apps/web/app/(marketing)/docs/_components/docs-card.tsx @@ -2,11 +2,13 @@ import Link from 'next/link'; import { ChevronRight } from 'lucide-react'; +import { Trans } from '@kit/ui/trans'; + export const DocsCard: React.FC< React.PropsWithChildren<{ title: string; subtitle?: string | null; - link: { url: string; label: string }; + link: { url: string; label?: string }; }> > = ({ title, subtitle, children, link }) => { return ( @@ -35,7 +37,7 @@ export const DocsCard: React.FC< className={'text-sm font-medium hover:underline'} href={link.url} > - {link.label} + {link.label ?? } diff --git a/apps/web/app/(marketing)/docs/_components/docs-cards.tsx b/apps/web/app/(marketing)/docs/_components/docs-cards.tsx index 568fef941..d17a0ad86 100644 --- a/apps/web/app/(marketing)/docs/_components/docs-cards.tsx +++ b/apps/web/app/(marketing)/docs/_components/docs-cards.tsx @@ -3,9 +3,11 @@ import { Cms } from '@kit/cms'; import { DocsCard } from './docs-card'; export function DocsCards({ cards }: { cards: Cms.ContentItem[] }) { + const cardsSortedByOrder = [...cards].sort((a, b) => a.order - b.order); + return ( -
- {cards.map((item) => { +
+ {cardsSortedByOrder.map((item) => { return ( ); diff --git a/apps/web/app/(marketing)/docs/_components/docs-navigation.tsx b/apps/web/app/(marketing)/docs/_components/docs-navigation.tsx index 5fd0c9504..ac3570bf4 100644 --- a/apps/web/app/(marketing)/docs/_components/docs-navigation.tsx +++ b/apps/web/app/(marketing)/docs/_components/docs-navigation.tsx @@ -12,6 +12,7 @@ import { isBrowser } from '@kit/shared/utils'; import { Button } from '@kit/ui/button'; import { Heading } from '@kit/ui/heading'; import { If } from '@kit/ui/if'; +import { Trans } from '@kit/ui/trans'; import { cn, isRouteActive } from '@kit/ui/utils'; const DocsNavLink: React.FC<{ @@ -24,14 +25,20 @@ const DocsNavLink: React.FC<{ const isFirstLevel = level === 0; return ( -
+
+ ); }; @@ -73,7 +80,11 @@ function Tree({ activePath: string; }) { return ( -
+
0, + })} + > {pages.map((treeNode, index) => ( - Table of Contents -
diff --git a/apps/web/app/(marketing)/docs/page.tsx b/apps/web/app/(marketing)/docs/page.tsx index f4d02cbbf..6681350fe 100644 --- a/apps/web/app/(marketing)/docs/page.tsx +++ b/apps/web/app/(marketing)/docs/page.tsx @@ -27,14 +27,16 @@ async function DocsPage() { return ( -
+
-
- +
+
+ +
diff --git a/apps/web/content/documentation/authentication/authentication.mdoc b/apps/web/content/documentation/authentication/authentication.mdoc new file mode 100644 index 000000000..59776220b --- /dev/null +++ b/apps/web/content/documentation/authentication/authentication.mdoc @@ -0,0 +1,24 @@ +--- +title: "Authentication" +description: "Learn how to set up authentication in your MakerKit application." +publishedAt: 2024-04-11 +order: 1 +--- + +MakerKit uses Supabase to manage authentication within your application. + +By default, every kit comes with the following built-in authentication methods: +- **Email/Password** - we added, by default, the traditional way of signing in +- **Third Party Providers** - we also added by default Google Auth sign-in +- **Email Links** +- **Phone Number** + +You're free to add (or remove) any of the methods supported by Supabase's +Authentication: we will see how. + +This documentation will help you with the following: + - **Setup** - setting up your Supabase project + - **SSR** - use SSR to persist your users' authentication, adding new +providers + - **Customization** - an overview of how MakerKit works so that you can adapt +it to your own application's needs \ No newline at end of file diff --git a/apps/web/content/documentation/authentication/configuration.mdoc b/apps/web/content/documentation/authentication/configuration.mdoc new file mode 100644 index 000000000..52222bf44 --- /dev/null +++ b/apps/web/content/documentation/authentication/configuration.mdoc @@ -0,0 +1,55 @@ +--- +title: "Configuration" +description: "Learn how authentication works in MakerKit and how to configure it." +publishedAt: 2024-04-11 +order: 0 +parent: "authentication/authentication" +--- + +The way you want your users to authenticate can be driven via configuration. + +If you open the global configuration at `src/configuration.ts`, you'll find +the `auth` object: + +```tsx title="configuration.ts" +import type { Provider } from '@supabase/gotrue-js/src/lib/types'; + +auth: { + requireEmailConfirmation: false, + providers: { + emailPassword: true, + phoneNumber: false, + emailLink: false, + oAuth: ['google'] as Provider[], + }, +} +``` + +As you can see, the `providers` object can be configured to only display the +auth methods we want to use. + +1. For example, by setting both `phoneNumber` and `emailLink` to `true`, the +authentication pages will display the `Email Link` authentication +and the `Phone Number` authentication forms. +2. Instead, by setting `emailPassword` to `false`, we will remove the +`email/password` form from the authentication and user profile pages. + +## Requiring Email Verification + +This setting needs to match what you have set up in Supabase. If you require email confirmation before your users can sign in, you will have to flip the following flag in your configuration: + +```ts +auth: { + requireEmailConfirmation: false, +} +``` + +When the flag is set to `true`, the user will not be redirected to the onboarding flow, but will instead see a successful alert asking them to confirm their email. After confirmation, they will be able to sign in. + +When the flag is set to `false`, the application will redirect them directly to the onboarding flow. + +## Emails sent by Supabase + +Supabase spins up an [InBucket](http://localhost:54324/) instance where all the emails are sent: this is where you can find emails related to password reset, sign-in links, and email verifications. + +To access the InBucket instance, you can go to the following URL: [http://localhost:54324/](http://localhost:54324/). Save this URL, you will use it very often. \ No newline at end of file diff --git a/apps/web/content/documentation/getting-started/getting-started.mdoc b/apps/web/content/documentation/getting-started/getting-started.mdoc new file mode 100644 index 000000000..86510f385 --- /dev/null +++ b/apps/web/content/documentation/getting-started/getting-started.mdoc @@ -0,0 +1,27 @@ +--- +title: "Getting started with Makerkit" +description: "Makerkit is a SaaS Starter Kit that helps you build a SaaS. Learn how to get started with Makerkit." +publishedAt: 2024-04-11 +order: 0 +--- + +Makerkit is a SaaS Starter Kit that helps you build a SaaS. It provides you with a set of tools and best practices to help you build a SaaS quickly and efficiently. + +## Getting started + +To get started with Makerkit, follow these steps: + +1. Sign up for an account on the [Makerkit website](https://makerkit.dev). +2. Create a new project by clicking on the "New Project" button. +3. Choose a template for your project. Makerkit provides several templates to help you get started quickly. + +## Features + +Makerkit provides the following features to help you build a SaaS: +1. User authentication +2. User management +3. Subscription management +4. Billing and payments +5. Super Admin + +... and many more! diff --git a/apps/web/content/documentation/getting-started/installing-dependencies.mdoc b/apps/web/content/documentation/getting-started/installing-dependencies.mdoc new file mode 100644 index 000000000..bf17f8e89 --- /dev/null +++ b/apps/web/content/documentation/getting-started/installing-dependencies.mdoc @@ -0,0 +1,21 @@ +--- +title: "Installing Dependencies" +description: "Learn how to install dependencies for your project." +publishedAt: 2024-04-11 +parent: "getting-started/getting-started" +order: 0 +--- + +To install dependencies in your project, please install `pnpm` by running the following command: + +```bash +npm install -g pnpm +``` + +Next, navigate to your project directory and run the following command: + +```bash +pnpm install +``` + +This will install all the dependencies listed in your `package.json` file. \ No newline at end of file diff --git a/apps/web/public/locales/en/marketing.json b/apps/web/public/locales/en/marketing.json index d35970b19..fd64e4418 100644 --- a/apps/web/public/locales/en/marketing.json +++ b/apps/web/public/locales/en/marketing.json @@ -11,6 +11,7 @@ "noPosts": "No posts found", "blogPaginationNext": "Next Page", "blogPaginationPrevious": "Previous Page", + "readMore": "Read more", "contactFaq": "If you have any questions, please contact us", "contact": "Contact", "about": "About", diff --git a/packages/cms/keystatic/src/client.ts b/packages/cms/keystatic/src/client.ts index f134e9718..30011b590 100644 --- a/packages/cms/keystatic/src/client.ts +++ b/packages/cms/keystatic/src/client.ts @@ -72,7 +72,13 @@ export class KeystaticClient implements CmsClient { return Promise.resolve(undefined); } - return this.mapPost({ entry: doc, slug: params.slug }, []); + const allPosts = await reader.collections[collection].all(); + + const children = allPosts.filter( + (item) => item.entry.parent === params.slug, + ); + + return this.mapPost({ entry: doc, slug: params.slug }, children); } async getCategories() {