Merge pull request #1112 from logto-io/gao-add-docs

docs(en-US): init get started

packages/docs/docs/tutorial/README.md

@@ -18,7 +18,7 @@ Main features:
 
 Boringly, we call it "[customer identity access management](https://en.wikipedia.org/wiki/Customer_identity_access_management)" (CIAM) or "customer identity solution."
 
-## Get Started
+## Installation
 
 ### Prerequisites
 
@@ -53,6 +53,6 @@ Heading to http://localhost:3001 to continue the Logto journey. Enjoy!
 
 TBD
 
-### Configuration
+## Configuration
 
 Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./tutorial/configuration) for detailed usage and full variable list.

packages/docs/docs/tutorial/configuration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 999
 ---
 
 # Configuration

packages/docs/docs/tutorial/get-started/README.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 2
+---
+
+# Get Started
+
+Before we start, it'll be good to know how Logto works. To simplify, we divide Logto into four parts: Admin Console, Sign-in Experience, Core Service, and SDKs.
+
+- **Admin Console** is a web app that will be your friend for customizing sign in and managing users.
+- **Sign-in Experience** is the UI that directly faces your end-users, including signing in, creating an account, etc.
+- **Core Service** is the foundation of Logto, which provides essential APIs to support everything else.
+- **SDKs** are the bridges between your application and Logto.
+
+:::note
+**TBD** need a simple infra figure here
+:::
+
+*Check out [API Reference](/api) If you want more advanced controls or programmatic access to Logto.*
+
+:::info
+Admin Console is the easiest way to customize and manage Sign-in Experience and Core Service, and we'll use it across the tutorial. 
+:::
+
+## Create an Admin Account
+
+After a successful installation, open the link in your terminal or access the Admin Console welcome page manually via `http://localhost:3001/welcome`.
+
+The welcome page briefly introduces Admin Console. Click "Create Account" to create an admin account.
+
+:::note
+For now, you cannot create multiple admin accounts via Admin Console, and only the first account will have admin access.
+:::
+
+On the create account page, enter your username and password to continue.
+
+## "Get Started" Tab
+
+Once you create the admin account, the browser will redirect you to the "Get Started" tab in Admin Console, which shows a few things that Logto can do at a glance.
+
+Our tutorial will follow the order you are seeing. So let's begin!

packages/docs/docs/tutorial/get-started/check-out-demo.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 1
+---
+
+# Check out the demo app
+
+Click the "Check out" button on the right, and the browser will open the demo app in a new tab. In this app, you can use your admin account credentials or create a new account to proceed.
+
+Like how you created the admin account, Logto natively supports username and password Sign-in Experience without configuration.
+
+:::note
+Logto has only one user identity system as the single source of truth, so you can use the same identity to sign in across multiple apps.
+:::
+
+The app itself is pretty simple: a congrats page with your Username and User ID, followed by a sign-out button.
+
+:::tip
+Sign out the demo app before further explorations. After finishing the "Customize sign-in experience" section, open the demo app again to see the changes.
+:::

packages/docs/docs/tutorial/get-started/create-and-integrate-the-first-app.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+import Columns from '@components/Columns';
+
+# Create and integrate the first application
+
+Click the "Create" button on the right, and the browser will redirect to the Application tab. Then click the "Create Application" button on this page.
+
+**Step 1**
+
+In the opening modal, choose which type of application you'd like to integrate:
+
+- **Native App** is an app that runs in a native environment. E.g., iOS app, Android app.
+- **Single Page App** is an app that runs in a web browser, which updates the page with the new data from the server without loading entire new pages. E.g., React DOM app, Vue app.
+- **Traditional Web App** is an app that renders and updates pages by the web server alone. E.g., JSP, PHP.
+
+We prepared different tutorials for each application type, and it'll be helpful if you choose the type properly.
+
+**Step 2**
+
+Enter the application name, e.g., "Bookstore," and click "Create Application."
+
+**Step 3**
+
+Ta-da! You just created your first application in Logto. You'll see a congrats page which includes a detailed integration guide. Follow the guide to see what the experience will be in your application.
+
+Meanwhile, Logto offers some official SDKs to bring the integration experience to another level (introduction included in the guide). You can also pick the guide from the list below if you skip the page by accident:
+
+<Columns columns={[
+  { title: 'Native App', items: [{ key: 'iOS' }, { key: 'Android' }] },
+  { title: 'Single Page App', items: [{ key: 'Vanilla JS' }, { key: 'React' }, { key: 'Vue' }] },
+  { title: 'Tranditional Web App', items: [{ key: 'ExpressJS' }, { key: 'Other Web Servers' }] },
+]} />

packages/docs/docs/tutorial/integrate-logto/README.md

@@ -1,4 +1,4 @@
-# Integrate SDK
+# Integrate Logto
 
 We provide a bunch of SDKs to let you integrate Logto with frontend clients with ease. If you are using traditional web technology (i.e., server directly renders frontend), please check out our integration guide.
 

packages/docs/docusaurus.config.js

@@ -124,7 +124,8 @@ const config = {
           '@components': path.resolve(__dirname, './src/components')
         } } })
       });
-    }
+    },
+    'docusaurus-plugin-sass'
   ]
 };
 

packages/docs/package.json

@@ -18,23 +18,26 @@
   "devDependencies": {
     "@algolia/client-search": "^4.13.0",
     "@docusaurus/core": "2.0.0-beta.21",
-    "@docusaurus/preset-classic": "2.0.0-beta.21",
-    "@docusaurus/theme-classic": "^2.0.0-beta.18",
-    "@mdx-js/react": "^1.6.22",
-    "clsx": "^1.1.1",
-    "prism-react-renderer": "^1.3.1",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
     "@docusaurus/module-type-aliases": "2.0.0-beta.21",
-    "@docusaurus/types": "^2.0.0-beta.18",
+    "@docusaurus/preset-classic": "2.0.0-beta.21",
+    "@docusaurus/theme-classic": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
+    "@mdx-js/react": "^1.6.22",
     "@tsconfig/docusaurus": "^1.0.5",
     "@types/node": "^17.0.23",
     "@types/react": "^17.0.14",
-    "typescript": "^4.6.3",
+    "clsx": "^1.1.1",
-    "redoc-cli": "^0.13.16",
+    "core-js": "^3.1.4",
+    "docusaurus-plugin-sass": "^0.2.2",
+    "prism-react-renderer": "^1.3.1",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
     "react-is": "^16.8.0",
-    "webpack": "^5.0.0",
+    "redoc-cli": "^0.13.16",
-    "core-js": "^3.1.4"
+    "sass": "^1.52.3",
+    "sass-loader": "^13.0.0",
+    "typescript": "^4.6.3",
+    "webpack": "^5.0.0"
   },
   "browserslist": {
     "production": [

packages/docs/src/components/Columns/index.module.scss

@@ -0,0 +1,12 @@
+.container {
+  display: flex;
+  justify-content: space-between;
+
+  > :not(:first-child) {
+    margin-left: 12px;
+  }
+
+  ul > li {
+    margin-left: -8px;
+  }
+}

packages/docs/src/components/Columns/index.tsx

@@ -0,0 +1,28 @@
+import React, { ReactNode } from 'react';
+import styles from './index.module.scss';
+
+export type Column = {
+  title: string;
+  items: Array<{ key: string; node?: ReactNode[]; }>;
+};
+
+type Props = {
+  columns: Column[];
+};
+
+const Columns = ({ columns }: Props) => {
+  return (
+    <div className={styles.container}>
+      {columns.map(({ title, items }) => (
+        <div key={title}>
+          <h4>{title}</h4>
+          <ul>
+            {items.map(({ key, node }) => (<li key={key}>{node ?? key}</li>))}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default Columns;