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,37 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzGithubEmbedProps {
+    repoPath: string;
+    height?: string;
+    openFile?: string;
+    startScript?: string;
+    clickToLoad?: boolean;
+}
+
+const StackBlitzGithubEmbed: React.FC<StackBlitzGithubEmbedProps> = ({
+    repoPath,
+    height = '600px',
+    openFile = 'main.ts',
+    clickToLoad = false,
+    startScript,
+}) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedGithubProject(containerRef.current, repoPath, {
+                openFile,
+                height,
+                view: 'editor',
+                hideNavigation: true,
+                startScript,
+                clickToLoad,
+            });
+        }
+    }, [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 Prisma Schema">
+            {children}
+        </Admonition>
+    );
+};
+
+export default ZModelVsPSL;

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

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

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
+    posts    Post[]
+  }
+
+  model Post {
+    id        String   @id @default(cuid())
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+    title     String
+    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,14 @@
+---
+description: ZenStack FAQ.
+
+slug: /faq
+sidebar_label: FAQ
+sidebar_position: 100
+---
+
+# 🙋🏻 FAQ
+
+## What databases are supported?
+
+Currently only SQLite and PostgreSQL are supported. MySQL will be added in the future. There's no plan to support other relational databases or NoSQL databases.
+

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

@@ -0,0 +1,4 @@
+position: 4
+label: Migration
+collapsible: true
+collapsed: true

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

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

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

@@ -0,0 +1,4 @@
+position: 2
+label: Data Modeling
+collapsible: true
+collapsed: true

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/conclusion.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 100
+description: Data modeling conclusion
+---
+
+# Conclusion
+
+Congratulations! You have learned all the essentials of data model with ZenStack. What's next?
+
+In the following parts, you'll learn how to put the schema into use and let it drive many aspects of your application, including:
+
+- [Creating an ORM to query the database](../orm/)
+- [Evolving database schema with migrations](../migration/)
+- [Exposing a data API with Query-as-a-Service](../service/)
+- [Driving other useful utilities](../service/)
+
+Let's continue our journey with ZenStack!

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)