docs: v3 docs structure

docusaurus.config.js

@@ -44,6 +44,10 @@ const config = {
                             label: '1.x',
                             banner: 'none',
                         },
+                        '3.x': {
+                            label: '3.0 Alpha',
+                            banner: 'none',
+                        },
                     },
                 },
                 blog: false,

package.json

@@ -22,6 +22,7 @@
         "@docusaurus/theme-mermaid": "3.4.0",
         "@giscus/react": "^2.4.0",
         "@mdx-js/react": "^3.0.1",
+        "@stackblitz/sdk": "^1.11.0",
         "autoprefixer": "^10.4.13",
         "clsx": "^1.2.1",
         "postcss": "^8.4.21",

src/components/StackBlitzEmbed.tsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzEmbedProps {
+    projectId: string;
+    height?: string;
+}
+
+const StackBlitzEmbed: React.FC<StackBlitzEmbedProps> = ({ projectId, height = '600px' }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedProjectId(containerRef.current, projectId, {
+                openFile: 'main.ts',
+                height,
+                view: 'editor',
+                forceEmbedLayout: true,
+            });
+        }
+    }, [projectId, height]);
+
+    return <div ref={containerRef} style={{ width: '100%', height }} />;
+};
+
+export default StackBlitzEmbed;

src/components/StackBlitzGithubEmbed.tsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzGithubEmbedProps {
+    repoPath: string;
+    height?: string;
+}
+
+const StackBlitzGithubEmbed: React.FC<StackBlitzGithubEmbedProps> = ({ repoPath, height = '600px' }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedGithubProject(containerRef.current, repoPath, {
+                openFile: 'main.ts',
+                height,
+                view: 'editor',
+                forceEmbedLayout: true,
+            });
+        }
+    }, [repoPath, height]);
+
+    return <div ref={containerRef} style={{ width: '100%', height }} />;
+};
+
+export default StackBlitzGithubEmbed;

versioned_docs/version-3.x/_components/PackageExec.tsx

@@ -0,0 +1,28 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    command: string;
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npx' },
+    { name: 'pnpm', command: 'pnpm' },
+    { name: 'bun', command: 'bunx' },
+    { name: 'yarn', command: 'npx' },
+];
+
+const PackageInstall = ({ command }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">{`${pkg.command} ${command}`}</CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/PackageInstall.tsx

@@ -0,0 +1,33 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    devDependencies: string[];
+    dependencies: string[];
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npm install', dev: '--save-dev' },
+    { name: 'pnpm', command: 'pnpm add', dev: '--save-dev' },
+    { name: 'bun', command: 'bun add', dev: '--dev' },
+    { name: 'yarn', command: 'yarn add', dev: '--dev' },
+];
+
+const PackageInstall = ({ devDependencies, dependencies }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">
+                        {`${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}${
+                            dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : ''
+                        }`}
+                    </CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/ZModelVsPSL.tsx

@@ -0,0 +1,16 @@
+import React, { FC } from 'react';
+import Admonition from '@theme/Admonition';
+
+interface ZModelVsPSLProps {
+    children: React.ReactNode;
+}
+
+const ZModelVsPSL: FC<ZModelVsPSLProps> = ({ children }) => {
+    return (
+        <Admonition type="info" title="🔋 ZModel vs PSL">
+            {children}
+        </Admonition>
+    );
+};
+
+export default ZModelVsPSL;

versioned_docs/version-3.x/_components/_zmodel-starter.md

@@ -0,0 +1,23 @@
+  ```zmodel
+  datasource db {
+    provider = 'sqlite'
+    url = "file:./dev.db"
+  }
+
+  model User {
+    id       String @id @default(cuid())
+    email    String @unique @email @length(6, 32)
+    posts    Post[]
+  }
+
+  model Post {
+    id        String   @id @default(cuid())
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+    title     String   @length(1, 256)
+    content   String
+    published Boolean  @default(false)
+    author    User     @relation(fields: [authorId], references: [id])
+    authorId  String
+  }
+  ```

versioned_docs/version-3.x/faq.md

@@ -0,0 +1,9 @@
+---
+description: ZenStack FAQ.
+
+slug: /faq
+sidebar_label: FAQ
+sidebar_position: 100
+---
+
+# 🙋🏻 FAQ

versioned_docs/version-3.x/migration/_category_.yml

@@ -0,0 +1,7 @@
+position: 4
+label: Migration
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: Migration

versioned_docs/version-3.x/migration/overview.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+description: ZenStack migration overview
+---
+
+# Overview

versioned_docs/version-3.x/modeling/_category_.yml

@@ -0,0 +1,7 @@
+position: 2
+label: Data Modeling
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: Data Modeling

versioned_docs/version-3.x/modeling/attribute.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 4
+description: Attributes in ZModel
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Attribute
+
+Attributes allow you to attach metadata to models and fields. As you've seen in the previous sections, they are used for many purposes, like adding unique constraints, mapping names, etc. Attributes are also indispensable for modeling relations between models.
+
+## Naming conventions
+
+By convention, attributes attached to models use a double `@@` prefix, while those for fields use a single `@` prefix.
+
+```zmodel
+model User {
+    id        Int    @id
+    email     String @unique
+
+    @@index([email, name])
+}
+```
+
+## Defining and applying attributes
+
+<ZModelVsPSL>
+Prisma schema doesn't allow users to define custom attributes, while ZModel allows it and uses it as a key mechanism for extensibility.
+</ZModelVsPSL>
+
+ZModel comes with a rich set of attributes that you can use directly. See [ZModel Language Reference](../reference/zmodel-language.md) for a complete list. You can also define your own custom attributes for specific purposes. Attributes are defined with a list of typed parameters. Parameters can named (default) or positional. Positional parameters can be passed with or without an explicit name. Parameters can also be optional.
+
+Here's an example for how the `@unique` attribute is defined:
+
+```zmodel
+attribute @unique(map: String?, length: Int?, sort: SortOrder?)
+```
+
+You can apply it in various ways:
+
+```zmodel
+model Foo {
+    x String @unique() // default application
+    y String @unique('y_unique') // positional parameter
+    z String @unique(map: 'z_unique', length: 10) // named parameter
+}
+```

versioned_docs/version-3.x/modeling/custom-type.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 7
+description: Custom types in ZModel
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Custom Type
+
+<ZModelVsPSL>
+Custom type is a ZModel concept and doesn't exist in PSL.
+</ZModelVsPSL>
+
+Besides models, you can also define custom types to encapsulate complex data structures. The main difference between a model and a custom type is that the latter is not backed by a database table.
+
+Here's a simple example:
+
+```zmodel
+type Address {
+    street  String
+    city    String
+    country String
+    zip     Int
+}
+```
+
+Custom types are defined exactly like models, with the exception that they cannot contain fields that are relations to other models. They can, however, contain fields that are other custom types.
+
+There are two ways to use custom types:
+
+```zmodel
+type Address {
+    street  String
+    city    String
+    country String
+    zip     Int
+}
+
+type UserProfile {
+    gender  String
+    address Address?
+}
+```
+
+- [Mixin](./mixin.md)
+- [Strongly typed JSON fields](./strong-typed-json.md)

versioned_docs/version-3.x/modeling/datasource.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+description: Datasource in ZModel
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+
+# Data Source
+
+The `datasource` block provides information about the database your application uses. The ORM relies on it to determine the proper SQL dialect to use when generating queries. If you use [Migration](../migration/), it must also have a `url` field that specifies the database connection string, so that the migration engine knows how to connect to the database. The `env` function can be used to reference environment variables so you can keep sensitive information out of the code.
+
+:::tip
+You can use both single quote and double quote for string literals.
+:::
+
+Each ZModel schema must have exactly one `datasource` block.
+
+<Tabs>
+
+<TabItem value="postgresql" label="PostgreSQL" default>
+```zmodel
+datasource db {
+    provider = 'postgresql'
+    url      = env('DATABASE_URL')
+}
+```
+</TabItem>
+
+<TabItem value="sqlite" label="SQLite">
+```zmodel
+datasource db {
+    provider = 'sqlite'
+    url      = 'file:./dev.db'
+}
+```
+</TabItem>
+
+</Tabs>
+
+Currently only PostgreSQL and SQLite are supported. MySql will be supported in a future release. There's no plan for other relational database types or NoSQL databases.
+
+<ZModelVsPSL>
+ZenStack's ORM runtime doesn't rely on the `url` information to connect to the database. Instead, you provide the information when constructing an ORM client. More on this in the [ORM](../orm/) section.
+</ZModelVsPSL>